knlist Subroutine

Purpose

Translates names to addresses in the running system.

Syntax

#include <nlist.h>

int knlist( NList, NumberOfElements, Size )
struct nlist *NList;
int NumberOfElements;
int Size;

Description

The knlist subroutine allows a program to look up the addresses of symbols exported by the kernel and kernel extensions.

The n_name field in the nlist structure specifies the name of a symbol for which the address is requested. If the symbol is found, its address is saved in the n_value field, and the remaining fields are not modified. If the symbol is not found, all fields, other than n_name, are set to 0.

In a 32-bit program, the n_value field is a 32-bit field, which is too small for some kernel addresses. To allow the addresses of all specified symbols to be obtained, 32-bit programs must use the nlist64 structure, which contains a 64-bit n_value field. For example, if NList64 is the address of an array of nlist64 structures, the knlist subroutine can be called as shown in the following example:

rc = knlist((struct nlist *)Nlist64,
                  NumberOfElements,
                  sizeof(structure nlist64));

The nlist and nlist64 structures include the following fields:

Table 1. Fields
Item	Description
`char *n_name`	Specifies the name of the symbol for which the address is to be retrieved.
`long n_value`	The address of the symbol, filled in by the knlist subroutine. This field is included in the nlist structure.
`long long n_value`	The address of the symbol, filled in by the knlist subroutine. This field is included in the nlist64 structure.

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

#undef n_name

Note:

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.
If the netdb.h file and either the nlist.h or syms.h file are included, the n_name field 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 the n_name field by entering:
```
#undef n_name
```
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 it, redefine the n_name field with:
```
#define n_name _n._n_name
```

Parameters

Table 2. Parameters
Item	Description
NList	Points to an array of nlist or nlist64 structures.
NumberOfElements	Specifies the number of structures in the array of nlist or nlist64 structures.
Size	Specifies the size of each structure. The only allowed values are `sizeof(struct nlist)` or `sizeof(struct nlist64)`.

Return Values

Upon successful completion, the knlist subroutine returns a value of 0. Otherwise, a value of -1 is returned, and the errno variable is set to indicate the error.

Error Codes

The knlist subroutine fails when one of the following is true:

Table 3. Error codes
Item	Description
EINVAL	The NumberOfElements parameters is less than 1 or the Size parameter is neither `sizeof(struct nlist)` nor `sizeof(struct nlist64)`.
EFAULT	The NList parameter is not a valid address. One or more symbols in the array specified by the Nlist parameter were not found. The address of one of the symbols does not fit in the n_value field. This is only possible if the caller is a 32-bit program and the Size parameter is `sizeof(struct nlist))`.