nlist64 Subroutine

Purpose

Gets entries from a name list.

Library

Standard C Library [libc.a]

Syntax

#include <nlist.h>

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

Description

The nlist64 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 nlist64 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 nlist64 subroutine runs in both 32-bit and 64-bit mode. The nlist64 subroutine runs in both 32-bit and 64-bit mode. nlist64 can read both 32-bit XCOFF and 64-bit XCOFF files in both 32-bit and 64-bit modes.

In 32-bit mode, the _n_name pointer variable in the nlist64 structure is 4 bytes wide. In the 64-bit mode, it is 8 bytes wide. In both 32-bit mode and 64-bit mode, the n_value variable (long long) is 8 bytes wide.

You can use the nlist64 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 nlist64 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 nlist64 or syment structure. If you need to access the n_name filed 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 nlist64 structure after undefining n_name, redefine n_name with:

   #define n_name _n._n_name

3. There is no nlist64 subroutine in libbsd.a

Parameters

Return Values

Upon successful completion, a 0 is returned.

If the file cannot be found or if it is not a valid name list, a value of -1 is returned.

Implementation Specifics

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

Related Information

The knlist subroutine.

The a.out file.

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