HP-UX Reference (11i v2 03/08) - 3 Library Functions N-Z (vol 7)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

100

nlist(3E) nlist(3E)

NAME

nlist( ), nlist64( ) - get entries from name list

SYNOPSIS

nlist()

cc [ﬂag ... ] cﬁle ...

-lelf [library ] ...

#include <nlist.h>

int nlist(const char *file_name, struct nlist *nl);

nlist64()

cc [ﬂag ... ] cﬁle ...

-lelf [library ] ...

#include <nlist.h>

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 and they can process SOM or ELF ﬁles.

The nlist structure is the same as nlist64 and is used for source code compatibility.

The

nlist/nlist64 function examines the name list in the executable ﬁle whose name is pointed to by

ﬁle_name, and selectively extracts a list of values and puts them in the array of

nlist/nlist64 struc-

tures pointed to by nl. The array of

nlist/nlist64

structures initially contains only the names of

variables. Once the

nlist/nlist64 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 ﬁle is searched for each variable name. If

the name is found, the symbol’s type, scope, and value in the ﬁle is inserted into the name list structure.

If the ﬁle searched is an ELF ﬁle, the section index is also inserted. For SOM ﬁles, the subspace index is

inserted. The symbol value is 64-bit. If the ﬁle searched is a SOM ﬁle, then the value ﬁeld is zero pad-

ded. If the name is not found, the ﬁelds in the name list structure are set to 0. The structures

nlist

and nlist64 are deﬁned in the include ﬁle <nlist.h>. See a.out(4) and nlist (4) for further descrip-

tion of the symbol table structure.

The ﬁle must have the organization and symbol table described for an

a.out ﬁle in a.out (4). The infor-

mation is extracted from the symbol table used by the linker, ld(1).

On machines that have such a ﬁle, this subroutine is useful for examining the system name list kept in

ﬁle

/stand/vmunix. In this way programs can obtain system addresses that are up to date.

RETURN VALUE

All

nlist structure ﬁelds are set to 0 if the ﬁle cannot be found or if it is not a valid object ﬁle contain-

ing a linker symbol table.

nlist() returns -1 upon error; otherwise it returns 0.

WARNINGS

The <

nlist.h> header ﬁle 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.