nlist Subroutine

Purpose

Gets entries from a name list.

Library

Standard C Library [libc.a]

Berkeley Compatibility Library [libbsd.a]

Syntax

#include <nlist.h>

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

Description

The nlist subroutine allows a program to examine the name list in the executable file named by the FileName parameter. It selectively extracts a list of values and places them in the array of nlist structures pointed to by the N1 parameter.

The name list specified by the N1 parameter consists of an array of structures containing names of variables, types, and values. The list is terminated with an element that has a null string in the name structure member. Each variable name is looked up in the name list of the file. If the name is found, the type and value of the name are inserted in the next two fields. The type field is set to 0 unless the file was compiled with the -g option. If the name is not found, both the type and value entries are set to 0.

All entries are set to 0 if the specified file cannot be read or if it does not contain a valid name list.

The nlist subroutine runs in both 32-bit and 64-bit mode. In 32-bit mode, nlist can read only 32-bit XCOFF format files and will give a -1 return code on a 64-bit XCOFF file. In 64-bit mode, nlist can read both 32-bit XCOFF format files and 64-bit XCOFF files.

In 32-bit mode, the _n_name pointer and the n_value variable in the nlist structure are 4 bytes wide, while in the 64-bit mode, they are both 8 bytes wide.

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

You can use the nlist subroutine to examine the system name list kept in the /unix file. By examining this list, you can ensure that your programs obtain current system addresses.

The nlist.h file is automatically included by a.out.h for compatibility. However, do not include the a.out.h file if you only need the information necessary to use the nlist subroutine. If you do include a.out.h, follow the #include statement with the line:

#undef n_name

Notes:

1. If both the nlist.h and netdb.h files are to be included, the netdb.h file should be included before the nlist.h file in order to avoid a conflict with the n_name structure member. Likewise, if both the a.out.h and netdb.h files are to be included, the netdb.h file should be included before the a.out.h file to avoid a conflict with the n_name structure.

2. If the netdb.h file and either the nlist.h or syms.h file are included, n_name will be defined as _n._n_name. This definition allows you to access the n_name field in the nlist or syment structure. If you need to access the n_name field in the netent structure, undefine n_name by including:

   #undef n_name

   in your code before accessing the n_name field in the netent structure. If you need to access the n_name field in a syment or nlist structure after undefining n_name, redefine n_name with:

   #define n_name _n._n_name

Parameters

Return Values

Upon successful completion, a 0 is returned. In BSD, the number of unfound namelist entries 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, compile with the libbsd.a library.

Implementation Specifics

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

Related Information

The knlist, nlist64 subroutine.

The a.out file.

Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.