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).
Page 1
getnetconfig(3N)getnetconfig(3N)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 ALSOnetconfig(4), getnetpath(3N), environ(5)
Page 2