getnetconfig(3N)                                              getnetconfig(3N)


NAME
     setnetconfig, getnetconfig, endnetconfig, getnetconfigent,
     freenetconfigent, nc_perror, nc_sperror - get network configuration
     database entry

SYNOPSIS
     #include <netconfig.h>

     void *setnetconfig(void);

     struct netconfig *getnetconfig(void *handlep);

     int endnetconfig(void *handlep);

     struct netconfig *getnetconfigent(char *netid);

     void freenetconfigent(struct netconfig *netconfigp);

     void nc_perror(const char *msg);

     char *nc_sperror(void);

DESCRIPTION
     The library routines described on this page are part of the Network
     Selection component.  They provide application access to the system
     network configuration database, /etc/netconfig.  In addition to the
     netconfig database and the routines for accessing it, Network Selection
     includes the environment variable NETPATH [see environ(5)] and the
     NETPATH access routines described in getnetpath(3N).

     A call to setnetconfig has the effect of ``binding'' or ``rewinding'' the
     netconfig database.  setnetconfig must be called before the first call to
     getnetconfig and may be called at any other time.  setnetconfig need not
     be called before a call to getnetconfigent.  setnetconfig returns a
     unique handle to be used by getnetconfig.

     When first called, getnetconfig returns a pointer to the current entry in
     the netconfig database, formatted as a netconfig structure.  getnetconfig
     can thus be used to search the entire netconfig file.  getnetconfig
     returns NULL at end of file.

     endnetconfig should be called when processing is complete to release
     resources for reuse.  Programmers should be aware, however, that the last
     call to endnetconfig frees all memory allocated by getnetconfig for the
     struct netconfig data structure.  endnetconfig may not be called before
     setnetconfig.  endnetconfig returns 0 on success and -1 on failure (for
     example, if setnetconfig was not called previously).

     getnetconfigent returns a pointer to the netconfig structure
     corresponding to netid.  It returns NULL if netid is invalid (that is,
     does not name an entry in the netconfig database).


     freenetconfigent frees the netconfig structure pointed to by netconfigp,
     previously returned by getnetconfigent.

     nc_perror prints a message to the standard error indicating why any of
     the above routines failed.  The message is prepended with the string msg
     and a colon.  A NEWLINE is appended at the end of the message.

     nc_sperror is similar to nc_perror but instead of sending the message to
     the standard error, will return a pointer to a string that contains the
     error message.

     nc_perror and nc_sperror can also be used with the NETPATH access
     routines described in getnetpath(3N).

RETURN VALUES
     setnetconfig returns a unique handle to be used by getnetconfig.  In the
     case of an error, setnetconfig returns NULL and nc_perror or nc_sperror
     can be used to print the reason for failure.

     getnetconfig returns a pointer to the current entry in the netconfig
     database, formatted as a struct netconfig (see netpath(4) for a
     description of the structure). getnetconfig returns NULL at the end of
     the file, or upon failure.

     endnetconfig returns 0 on success and -1 on failure (for example, if
     setnetconfig was not called previously).

     On success, getnetconfigent returns a pointer to the struct netconfig
     structure corresponding to netid; otherwise it returns NULL.

     nc_sperror returns a pointer to a static buffer which contains the error
     message string.  This buffer is overwritten on each call.  Neither
     nc_sperror or nc_perror are multi-thread safe.

NOTES
     Prior to 6.5.20, these functions were present in the UNIX System V
     Networking Library (libnsl) and only available to applications linking
     against that library.  In 6.5.20, they were moved to the IRIX standard C
     library (libc).  Applications using these functions by linking against
     libnsl will continue to work on all releases of IRIX.  Authors of new
     applications which use these functions without linking against libnsl
     should be aware that their applications will not run on releases of IRIX
     prior to 6.5.20, and should use the _MIPS_SYMBOL_PRESENT macro to provide
     a graceful fallback.

SEE ALSO
     netconfig(4), getnetpath(3N), environ(5)


                                                                        Page 2