nlist, nlist64 Subroutine

Purpose

Gets entries from a name list.

Library

Standard C Library (libc.a)

Berkeley Compatibility Library [libbsd.a] for the nlist subroutine, 32-bit programs, and POWER® processor-based platforms

Syntax

#include <nlist.h>

int nlist ( FileName, NL )
const char *FileName;
struct nlist *NL;

int nlist64 ( FileName, NL64 )
const char *FileName;
struct nlist64 *NL64;

Description

The nlist and nlist64 subroutines examine the name list in the object file named by the FileName parameter. The subroutine selectively reads a list of values and stores them into an array of nlist or nlist64 structures pointed to by the NL or NL64 parameter, respectively.

The name list specified by the NL or NL64 parameter consists of an array of nlist or nlist64 structures containing symbol names and other information. The list is terminated with an element that has a null pointer or a pointer to a null string in the n_name structure member. Each symbol name is looked up in the name list of the file. If the name is found, the value of the symbol is stored in the structure, and the other fields are filled in. If the program was not compiled with the -g flag, the n_type field may be 0.

If multiple instances of a symbol are found, the information about the last instance is stored. If a symbol is not found, all structure fields except the n_name field are set to 0. Only global symbols will be found.

The nlist and nlist64 subroutines run in both 32-bit and 64-bit programs that read the name list of both 32-bit and 64-bit object files, with one exception: in 32-bit programs, nlist will return -1 if the specified file is a 64-bit object file.

The nlist and nlist64 subroutines are used to read the name list from XCOFF object files.

The nlist64 subroutine can be used to examine the system name list kept in the kernel, by specifying /unix as the FileName parameter. The knlist subroutine can also be used to look up symbols in the current kernel namespace.

Note: The nlist.h header file has a #define field for n_name. If a source file includes both nlist.h and netdb.h, there will be a conflict with the use of n_name. If netdb.h is included after nlist.h, n_name will be undefined. To correct this problem, _n._n_name should be used instead. If netdb.h is included before nlist.h, and you need to refer to the n_name field of struct netent, you should undefine n_name by entering: 
#undef n_name

The nlist subroutine in libbsd.a is supported only in 32-bit mode.

Parameters

Item Description
FileName Specifies the name of the file containing a name list.
NL Points to the array of nlist structures.
NL64 Points to the array of nlist64 structures.

Return Values

Upon successful completion, a 0 is returned, even if some symbols could not be found. In the libbsd.a version of nlist, the number of symbols not found in the object file's name list is returned. If the file cannot be found or if it is not a valid name list, a value of -1 is returned.

Compatibility Interfaces

To obtain the BSD-compatible version of the subroutine 32-bit applications, compile with the libbsd.a library by using the -lbsd flag.