minix/lib/libc/rpc/getnetpath.3
Ben Gras 2fe8fb192f Full switch to clang/ELF. Drop ack. Simplify.
There is important information about booting non-ack images in
docs/UPDATING. ack/aout-format images can't be built any more, and
booting clang/ELF-format ones is a little different. Updating to the
new boot monitor is recommended.

Changes in this commit:

	. drop boot monitor -> allowing dropping ack support
	. facility to copy ELF boot files to /boot so that old boot monitor
	  can still boot fairly easily, see UPDATING
	. no more ack-format libraries -> single-case libraries
	. some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases
	. drop several ack toolchain commands, but not all support
	  commands (e.g. aal is gone but acksize is not yet).
	. a few libc files moved to netbsd libc dir
	. new /bin/date as minix date used code in libc/
	. test compile fix
	. harmonize includes
	. /usr/lib is no longer special: without ack, /usr/lib plays no
	  kind of special bootstrapping role any more and bootstrapping
	  is done exclusively through packages, so releases depend even
	  less on the state of the machine making them now.
	. rename nbsd_lib* to lib*
	. reduce mtree
2012-02-14 14:52:02 +01:00

124 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