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)