NAME
nlist(), nlist64() — get entries from name list
SYNOPSIS
#include <nlist.h>
int nlist(const char *file_name, struct nlist *nl);
int nlist64(const char* file_name, struct nlist64 *nl);
Remarks
The use of symbol table
type and value information is inherently non-portable.
Use of
nlist()
or
nlist64()
should reduce the effort required
to port a program that uses such information,
but complete portability across all
HP-UX
implementations cannot be expected.
DESCRIPTION
nlist()
and
nlist64()
have basically the same functionality except
nlist64()
uses a new nlist structure,
nlist64,
and can process
Som
or
Elf
files.
nlist()
can only process Som files and uses the
nlist
structure.
The
nlist
function examines the name list in the executable file
whose name is pointed to by
file_name,
and selectively extracts a list of values
and puts them in the array of
nlist/nlist64
structures pointed to by
nl.
The array of
nlist/nlist64
structures initially contains only the names of variables.
Once the
nlist
function has been called,
the variable names are augmented with symbol information.
The list is terminated by a null name,
which consists of a null string
in the variable-name position of the structure.
The name list of the file is searched for each variable name.
If the name is found, the symbol's type, scope, and value in the file
is inserted into the name list structure. For
nlist64(),
if the file searched is an Elf file, the section index is also inserted.
For
nlist()
and Som files, the subspace index is inserted.
On wide mode systems, the symbol value is 64 bits. If the
file searched is a Som file, then the value field is zero padded.
If the name is not found, the fields in the name list structure are set to 0.
The structures
nlist
and
nlist64
are defined in the include file
<nlist.h>.
See
a.out(4)
and
nlist(4)
for further description of the symbol table structure.
The file must have the organization
and symbol table described for an
a.out
file in
a.out(4).
The information is extracted from the symbol table
used by the loader,
ld(1).
On machines that have such a file, this subroutine is useful
for examining the system name list kept in file
/stand/vmunix.
In this way programs can obtain system addresses that are up to date.
RETURN VALUE
All nlist structure fields are set to 0 if the file cannot be found
or if it is not a valid object file containing a linker symbol table.
nlist()
returns -1 upon error; otherwise it returns 0.
WARNINGS
The
<nlist.h>
header file is automatically included by
<a.out.h>
for compatibility.
However, including
<a.out.h>
is discouraged if the only information needed from
<a.out.h>
is for use by
nlist().
If
<a.out.h>
is included, the line
#undef n_name
may need to follow it.
STANDARDS CONFORMANCE
nlist(): SVID2, SVID3
