123 lines
2.9 KiB
Groff
123 lines
2.9 KiB
Groff
.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
|
|
.\" $NetBSD: getnetpath.3,v 1.3 2002/02/07 07:00:23 ross 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
|
|
.Fd #include \*[Lt]netconfig.h\*[Gt]
|
|
.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 NETPATH
|
|
environment variable (see
|
|
.Xr environ 7 ) .
|
|
See
|
|
.Xr getnetconfig 3
|
|
for other routines that also access the
|
|
network configuration database directly.
|
|
The 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
|
|
NETPATH component.
|
|
The netconfig entry is formatted as a struct netconfig.
|
|
On each subsequent call,
|
|
.Fn getnetpath
|
|
returns a pointer to the netconfig entry that corresponds to the next
|
|
valid NETPATH component.
|
|
.Fn getnetpath
|
|
can thus be used to search the netconfig database for all networks
|
|
included in the NETPATH variable.
|
|
When NETPATH has been exhausted,
|
|
.Fn getnetpath
|
|
returns NULL.
|
|
.Pp
|
|
A call to
|
|
.Fn setnetpath
|
|
.Dq binds
|
|
to or
|
|
.Dq rewinds
|
|
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 NETPATH
|
|
components.
|
|
A NETPATH component is invalid if there is no corresponding
|
|
entry in the netconfig database.
|
|
.Pp
|
|
If the NETPATH variable is unset,
|
|
.Fn getnetpath
|
|
behaves as if 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 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 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 NULL.
|
|
.Pp
|
|
.Fn endnetpath
|
|
returns 0 on success and -1 on failure
|
|
(for example, if
|
|
.Fn setnetpath
|
|
was not called previously).
|
|
.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 NETPATH component. When NETPATH has been exhausted,
|
|
.Fn getnetpath
|
|
returns NULL.
|
|
.Sh SEE ALSO
|
|
.Xr getnetconfig 3 ,
|
|
.Xr netconfig 5 ,
|
|
.Xr environ 7
|