125 lines
2.8 KiB
Groff
125 lines
2.8 KiB
Groff
|
.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4
|
||
|
|
.\" $NetBSD: getnetpath.3,v 1.6 2003/04/16 13:34:43 wiz 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 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
|