nlist(3)                            CLIX                            nlist(3)



  NAME

    nlist - Gets entries from name list

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <nlist.h>

    int nlist(
      char *filename ,
      struct nlist *nl );

  PARAMETERS

    filename   Pointer to the name of the executable file whose name list is
               to be returned.

    nl         Pointer to an array of nlist() structures.  The structure
               contains names, types, and values of variables.  The user fills
               in the names wanted, and the function nlist() fills in the type
               and value information for the selected variables.

  DESCRIPTION

    The nlist() function examines the name list in the executable file whose
    name is pointed to by filename, and selectively extracts a list of values
    and puts them in the array of nlist structures pointed to by nl.  The name
    list nl consists of an array of structures containing names of variables,
    types, and values.  The list is terminated with a null name; that is, a
    null string is in the name position of the structure.  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
    will be set to 0 unless the file was compiled with the -g flag.  If the
    name is not found, both entries are set to 0.

    This function is useful for examining the system name list kept in the
    file /unix.  In this way programs can obtain system addresses that are up
    to date.  See a.out for a discussion of the symbol table structure.

  EXAMPLES

    In the following code fragment, nlist():

    ⊕  examines the name list in the executable file pointed to by myexe.

    ⊕  extracts the list of mylist[N].* values.




  2/94 - Intergraph Corporation                                              1

  nlist(3)                            CLIX                            nlist(3)



    ⊕  puts the mylist[N].* values list in the array of nlist structures
       pointed to by mylist.

    As follows:

    #include <nlist.h>
         .
         .
         .
    int  st;
    struct nlist mylist[3];
    mylist[0].n_name = "temp_var1";
    mylist[1].n_name = "temp_var2";
    mylist[2].n_name = NULL;

    st = nlist("myexe", mylist);
         .
         .
         .


  FILES

    /unix

  NOTES

    The <nlist.h> header file is automatically included by <a.out.h> for
    compatibility.  However, if the only information needed from <a.out.h> is
    for use of nlist(), then including <a.out.h> is discouraged.  If <a.out.h>
    is included, the line #undef n_name may need to follow it.

  CAUTIONS

    If the file cannot be read or if it does not contain a valid name list,
    all value entries are set to 0.

  RETURN VALUES

    The nlist() function returns a -1 value when:

    ⊕  an error occurs such as when an executable file cannot be opened.

    ⊕  a file has a bad magic number.

    ⊕  internal memory allocation fails.

    If the function is successful, a value of 0 is returned.

  RELATED INFORMATION




  2                                              Intergraph Corporation - 2/94

  nlist(3)                            CLIX                            nlist(3)



    Files:  a.out(4)





















































  2/94 - Intergraph Corporation                                              3