[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

nlist, nlist64 Subroutine


Gets entries from a name list.


Standard C Library [libc.a] for POWER-based platforms

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

ELF Object File Access Library [libelf.so] for Itanium-based platforms


#include <nlist.h>

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

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


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 n_name are set to 0. On POWER-based platforms, only global symbols will be found. On Itanium-based platforms, information about both static and global symbols can be retrieved.

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.

On POWER-based platforms, nlist and nlist64 are used to read the name list from XCOFF object files.

On Itanium-based platforms, nlist and nlist64 are used to read the name list from ELF 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. On Itanium-based platforms, an additional interface, getksym, is available for examining symbols in a running kernel, including dynamically loaded kernel extensions.

Note: On POWER-based platforms, 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


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 for POWER-based platforms and 32-bit applications, compile with the libbsd.a library by using the -lbsd flag.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

The nlist subroutine in libbsd.a is supported only in 32-bit mode on POWER-based platforms.

Related Information

The knlist subroutine.

The a.out file in XCOFF format.

The a.out file in ELF format.

Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]