\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
\" $NetBSD: getnetpath.3,v 1.7 2022/12/04 23:02:57 uwe Exp $
\" Copyright 1989 AT&T
Dd April 22, 2000
Dt GETNETPATH 3
Os
Sh NAME
Nm getnetpath ,
Nm setnetpath ,
Nm endnetpath
Nd get /etc/netconfig entry corresponding to NETPATH component
Sh LIBRARY
Lb libc
Sh SYNOPSIS
In netconfig.h
Ft struct netconfig *
Fn getnetpath "void *handlep"
Ft void *
Fn setnetpath "void"
Ft int
Fn endnetpath "void *handlep"
Sh DESCRIPTION
The routines described in this page provide the application access to the system
network configuration database,
Pa /etc/netconfig ,
as it is
Dq filtered
by the
Ev NETPATH
environment variable
Po see
Xr environ 7
Pc .
See
Xr getnetconfig 3
for other routines that also access the
network configuration database directly.
The
Ev NETPATH
variable is a list of colon-separated network identifiers.
Pp
Fn getnetpath
returns a pointer to the
netconfig database entry corresponding to the first valid
Ev NETPATH
component.
The netconfig entry is formatted as a
Vt struct netconfig .
On each subsequent call,
Fn getnetpath
returns a pointer to the netconfig entry that corresponds to the next
valid
Ev NETPATH
component.
Fn getnetpath
can thus be used to search the netconfig database for all networks
included in the
Ev NETPATH
variable.
When
Ev NETPATH
has been exhausted,
Fn getnetpath
returns
Dv NULL .
Pp
A call to
Fn setnetpath
Dq binds
to or
Dq rewinds
Ev NETPATH .
Fn setnetpath
must be called before the first call to
Fn getnetpath
and may be called at any other time.
It returns a handle that is used by
Fn getnetpath .
Pp
Fn getnetpath
silently ignores invalid
Ev NETPATH
components.
A
Ev NETPATH
component is invalid if there is no corresponding
entry in the netconfig database.
Pp
If the
Ev NETPATH
variable is unset,
Fn getnetpath
behaves as if
Ev NETPATH
were set to the sequence of
Dq default
or
Dq visible
networks in the netconfig database, in the
order in which they are listed.
\"This proviso holds also for this
\"whole manpage.
Pp
Fn endnetpath
may be called to
Dq unbind
from
Ev NETPATH
when processing is complete, releasing resources for reuse.
Programmers should be aware, however, that
Fn endnetpath
frees all memory allocated by
Fn getnetpath
for the
Vt struct netconfig
data structure.
Sh RETURN VALUES
Fn setnetpath
returns a handle that is used by
Fn getnetpath .
In case of an error,
Fn setnetpath
returns
Dv NULL .
Pp
Fn endnetpath
returns 0 on success and \-1 on failure
Po
for example, if
Fn setnetpath
was not called previously
Pc .
Fn nc_perror
or
Fn nc_sperror
can be used to print out the reason for failure.
See
Xr getnetconfig 3 .
Pp
When first called,
Fn getnetpath
returns a pointer to the netconfig database entry corresponding to the first
valid
Ev NETPATH
component.
When
Ev NETPATH
has been exhausted,
Fn getnetpath
returns
Dv NULL .
Sh SEE ALSO
Xr getnetconfig 3 ,
Xr netconfig 5 ,
Xr environ 7
