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

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

101

102

103

104

105

106

107

108

109

110

nlist(3C) nlist(3C)

(For PA-RISC Systems)

NAME

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

SYNOPSIS

nlist()

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

#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 except

nlist64() uses a new nlist

structure,

nlist64, and can process SOM or ELF ﬁles. nlist() can only process SOM ﬁles and uses

the nlist structure.

The

nlist 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

structures

pointed to by nl. The array of

nlist/nlist64

structures initially contains only the names of vari-

ables. Once the

nlist function has been called, the variable names are augmented with symbol infor-

mation. The list is terminated by a null name, which consists of a null string in the variable-name posi-

tion 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. For

nlist64(),if

the ﬁle searched is an ELF ﬁle, the section index is also inserted. For

nlist() and SOM ﬁles, the sub-

space index is inserted. On wide mode systems, the symbol value is 64-bit. If the ﬁle searched is a SOM

ﬁle, then the value ﬁeld is zero padded. 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 description 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 containing 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.