GETNETPATH(3NSL) Networking Services Library Functions GETNETPATH(3NSL)
NAME
getnetpath, setnetpath, endnetpath - get /etc/netconfig entry
corresponding to NETPATH component
SYNOPSIS
#include <netconfig.h>
struct netconfig *getnetpath(
void *handlep);
void *setnetpath(
void);
int endnetpath(
void *handlep);
DESCRIPTION
The routines described on this page are part of the Network Selection
component. They provide the application access to the system network
configuration database,
/etc/netconfig, as it is "filtered" by the
NETPATH environment variable. See
environ(7). See
getnetconfig(3NSL) for other routines that also access the network configuration
database directly. The
NETPATH variable is a list of colon-separated
network identifiers.
getnetpath() returns a pointer to the
netconfig database entry
corresponding to the first valid
NETPATH component. The
netconfig entry is formatted as a
struct netconfig. On each subsequent call,
getnetpath() returns a pointer to the
netconfig entry that
corresponds to the next valid
NETPATH component.
getnetpath() can
thus be used to search the
netconfig database for all networks
included in the
NETPATH variable. When
NETPATH has been exhausted,
getnetpath() returns NULL.
A call to
setnetpath() "binds" to or "rewinds"
NETPATH.
setnetpath() must be called before the first call to
getnetpath() and may be
called at any other time. It returns a handle that is used by
getnetpath().
getnetpath() silently ignores invalid
NETPATH components. A
NETPATH component is invalid if there is no corresponding entry in the
netconfig database.
If the
NETPATH variable is
unset,
getnetpath() behaves as if
NETPATH were set to the sequence of "default" or "visible" networks in the
netconfig database, in the order in which they are listed.
endnetpath() may be called to "unbind" from
NETPATH when processing
is complete, releasing resources for reuse. Programmers should be
aware, however, that
endnetpath() frees all memory allocated by
getnetpath() for the
struct netconfig data structure.
endnetpath() returns
0 on success and
-1 on failure (for example, if
setnetpath() was not called previously).
RETURN VALUES
setnetpath() returns a handle that is used by
getnetpath(). In case
of an error,
setnetpath() returns
NULL. nc_perror() or
nc_sperror() can be used to print out the reason for failure. See
getnetconfig(3NSL).
When first called,
getnetpath() returns a pointer to the
netconfig database entry corresponding to the first valid
NETPATH component.
When
NETPATH has been exhausted,
getnetpath() returns NULL.
endnetpath() returns
0 on success and
-1 on failure (for example, if
setnetpath() was not called previously).
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+
SEE ALSO
getnetconfig(3NSL),
netconfig(5),
attributes(7),
environ(7) December 30, 1996 GETNETPATH(3NSL)
