getnetconfig(3)

NAME

getnetconfig, setnetconfig, endnetconfig, getnetconfigent, freenetconfigent, nc_perror, nc_sperror - get network con

figuration
database entry

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <netconfig.h>
struct netconfig *
getnetconfig(void *handlep);
void *
setnetconfig(void);
int
endnetconfig(void *handlep);
struct netconfig *
getnetconfigent(const 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 provide the ap

plication
access to the system network configuration database,

/etc/netconfig. The
getnetconfig() function returns a pointer to the current en

try in the
netconfig database, formatted as a struct netconfig. Suc

cessive calls
will return successive netconfig entries in the netconfig

database. The
getnetconfig() function can be used to search the entire

netconfig file.
The getnetconfig() function returns NULL at the end of the

file. The
handlep argument is the handle obtained through

setnetconfig().

A call to setnetconfig() has the effect of ``binding'' to or ``rewinding'' the netconfig database. The setnetconfig()

function must
be called before the first call to getnetconfig() and may be

called at
any other time. The setnetconfig() function need not be

called before a
call to getnetconfigent(). The setnetconfig() function re

turns a unique
handle to be used by getnetconfig().

The endnetconfig() function should be called when processing

is complete
to release resources for reuse. The handlep argument is the

handle
obtained through setnetconfig(). Programmers should be

aware, however,
that the last call to endnetconfig() frees all memory allo

cated by
getnetconfig() for the struct netconfig data structure. The endnetconfig() function may not be called before

setnetconfig().

The getnetconfigent() function returns a pointer to the net

config structure corresponding to netid. It returns NULL if netid is

invalid (that
is, does not name an entry in the netconfig database).

The freenetconfigent() function frees the netconfig struc

ture pointed to
by netconfigp (previously returned by getnetconfigent()).

The nc_perror() function 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 character is appended

at the end
of the message.

The nc_sperror() function is similar to nc_perror() but in

stead of sending the message to the standard error, will return a pointer

to a string
that contains the error message.

The nc_perror() and nc_sperror() functions can also be used

with the
NETPATH access routines defined in getnetpath(3).

RETURN VALUES

The setnetconfig() function returns a unique handle to be

used by
getnetconfig(). In the case of an error, setnetconfig() re

turns NULL and
nc_perror() or nc_sperror() can be used to print the reason

for failure.

The getnetconfig() function returns a pointer to the current

entry in the
netconfig database, formatted as a struct netconfig. The

getnetconfig()
function returns NULL at the end of the file, or upon fail

ure.

The endnetconfig() function 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.

The nc_sperror() function returns a pointer to a buffer

which contains
the error message string. This buffer is overwritten on

each call. In
multithreaded applications, this buffer is implemented as

thread-specific
data.

FILES

/etc/netconfig

SEE ALSO

getnetpath(3), netconfig(5)

BSD April 22, 2000

BSD