.TH coffnlist() "" "" "General Function (libc)"
.PC "Symbol table lookup, COFF format"
.B "#include <coff.h>"
\fBcoffnlist(\fIfn\^\fB, \fInlp\^\fB, \fInames\^\fB, \fIcount\^\fB)\fR
\fBchar *\fIfn\^\fB;\fR
\fBSYMENT *\fInlp\^\fB;\fR
\fBchar *\fInames\^\fB;\fR
\fBint \fIcount\^\fB;\fR
.PP
The function
.B coffnlist()
finds one or more names in the symbol table of a file
in the COFF format.
.PP
You must arrange the names you seek into the form of a COFF symbol table.
All long names (i.e., names longer than four characters)
must be strung together like the COFF long-symbol-name section.
Give each name an
.B n_type
of \-1.
After the call, any unfound names will still have this
.BR n_type ,
as a sign that it could not be found.
Thus, you can use the same table to search several different COFF files.
.PP
.I fn
points to the name of the file to be searched.
.I nlp
points to an array of type
.BR SYMENT .
This structure is defined in header file
.B coff.h
as follows:
.DM
typedef	struct	syment	{
	union	{
		char _n_name[SYMNMLEN]; /* Name */
		struct {
			long _n_zeroes; /* If name[0-3] zero, */
			long _n_offset; /* string table offset */
		} _n_n;
		char *_n_nptr[2];
	} _n;
	long		n_value;	/* Value */
	short		n_scnum;	/* Section number */
	unsigned short n_type;	/* Type */
	char		n_sclass;	/* Storage class */
	char		n_numaux;	/* Auxilliary entries */
#pragma align 2
} SYMENT;
#pragma align
.DE
.PP
.I count
gives the number of symbols being sought.
If there are long names, the displacement works from the
.I names
parameter.
.PP
Each item being sought must have 0xFFFF in its
.B n_type
field.
This allows
.B coffnlist()
to be used on several files in order.
.PP
.B coffnlist()
opens and reads the file pointed to by
.IR fn .
It then scans the symbol table and tries to find a symbol with an
.B n_type
of 0xFFFF.
Upon finding this entry,
.B coffnlist()
fills in the fields of the symbol entry.
.PP
.B coffnlist()
returns zero if anything goes wrong, such as an inability to open the file
.IR fn .
Otherwise, it returns one.
.SH Example
The following example looks up three symbol names in the symbol table of
file
.BR tx.o .
.DM
#include <stdio.h>
#include <coff.h>
.DE
.DM
main()
 {
	int i;
	static SYMENT sym[3];	/* the table of names to find */
.DE
.DM
				
	/* the long names section */
	static char long_names[] = "a_very_long_name";
	strcpy(sym[0].n_name, "x");	/* look up x */
	sym[0].n_type = -1;
.DE
.DM
	strcpy(sym[1].n_name, "y");	/* look up y */
	sym[1].n_type = -1;
.DE
.DM
	sym[2].n_zeroes = 0;	/* look up a_very_long_name */
	/* the long name table starts with a long giving its length
 	 * offsets are from the beginning of that long. Therefore
	 * the n_offset of the first field is 4 not zero */
	sym[2].n_offset = sizeof(long);
	sym[2].n_type = -1;
.DE
.DM
	/* do lookups */
	if (!coffnlist("tx.o", sym, long_names, 3))
		exit(1);
.DE
.DM
	/* show off results */
	for (i = 0; i < 3; i++) {
		if (sym[i].n_type != -1)
			printf("%s found at %x\en",
				(sym[i].n_zeroes ? sym[i].n_name :
					long_names + sym[i].n_offset - sizeof(long)),
					sym[i].n_value);
	}
}
.DE
.SH "See Also"
.Xr "coff.h," coff.h
.Xr "libc," libc
.Xr "nlist()" nlist
