78 lines
3.0 KiB
Plaintext
78 lines
3.0 KiB
Plaintext
'\"macro stdmacro
|
|
.if n .pH g3n.getnetpath @(#)getnetpath 40.17 of 5/21/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.nr X
|
|
.if \nX=0 .ds x} getnetpath 3N "Networking Support Utilities" "\&"
|
|
.if \nX=1 .ds x} getnetpath 3N "Networking Support Utilities"
|
|
.if \nX=2 .ds x} getnetpath 3N "" "\&"
|
|
.if \nX=3 .ds x} getnetpath "" "" "\&"
|
|
.TH \*(x}
|
|
.SH NAME
|
|
\f4getnetpath\f1 \- get netconfig entry corresponding to \f4NETPATH\f1 component
|
|
.SH "SYNOPSIS"
|
|
.nf
|
|
\f4#include <netconfig.h>
|
|
.sp .5
|
|
void *setnetpath(void);
|
|
struct netconfig *getnetpath(void \(**handlep);
|
|
int endnetpath(void \(**handlep);\f1
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
The three routines described on this page are
|
|
part of the UNIX System V Network Selection
|
|
component.
|
|
They provide application access to the system
|
|
network configuration database, \f4/etc/netconfig\f1, as it
|
|
is ``filtered'' by
|
|
the \f4NETPATH\f1 environment variable [see \f4environ\f1(5)].
|
|
Network Selection also includes routines that access the
|
|
network configuration database directly [see \f4getnetconfig\f1(3N)].
|
|
.P
|
|
A call to \f4setnetpath\f1 ``binds'' or
|
|
``rewinds'' \f4NETPATH\f1.
|
|
\f4setnetpath\f1 must be called before the first call to \f4getnetpath\f1
|
|
and may be called at any other time.
|
|
It returns a handle that is used by \f4getnetpath\f1.
|
|
\f4setnetpath\f1 will fail if the \f4netconfig\f1 database is not present.
|
|
If \f4NETPATH\f1 is unset, \f4setnetpath\f1 returns
|
|
the number of ``visible'' networks in the \f4netconfig\f1 file.
|
|
The set of visible networks constitutes a default \f4NETPATH\f1.
|
|
.P
|
|
When first called, \f4getnetpath\f1 returns a pointer to the
|
|
\f4netconfig\f1 database entry corresponding to the first
|
|
valid \f4NETPATH\f1 component.
|
|
The \f4netconfig\f1 entry is formatted as a \f(CWnetconfig\f1 structure.
|
|
On each subsequent call, \f4getnetpath\f1 returns a pointer to the
|
|
\f4netconfig\f1 entry
|
|
that corresponds to the next
|
|
valid \f4NETPATH\f1 component.
|
|
\f4getnetpath\f1 can thus be
|
|
used to search the \f4netconfig\f1 database for all networks
|
|
included in the \f4NETPATH\f1 variable.
|
|
When \f4NETPATH\f1 has been exhausted, \f4getnetpath\f1 returns
|
|
\f4NULL\f1.
|
|
.P
|
|
\f4getnetpath\f1 silently ignores invalid
|
|
\f4NETPATH\f1 components.
|
|
A \f4NETPATH\f1 component is invalid if there is no corresponding
|
|
entry in the \f4netconfig\f1 database.
|
|
.P
|
|
If the \f4NETPATH\f1 variable is unset, \f4getnetpath\f1
|
|
behaves as if \f4NETPATH\f1 were set to the sequence of
|
|
``default'' or ``visible'' networks in the \f4netconfig\f1 database, in the
|
|
order in which they are listed.
|
|
.\"This proviso holds also for this
|
|
.\"whole manpage.
|
|
.P
|
|
\f4endnetpath\f1 may be called to ``unbind'' \f4NETPATH\f1
|
|
when processing is complete,
|
|
releasing resources for reuse.
|
|
Programmer's should be aware, however, that \f4endnetpath\f1 frees all
|
|
memory allocated by \f4setnetpath\f1.
|
|
\f4endnetpath\f1 returns \f40\f1 on success and \f4\-1\f1 on failure
|
|
(for example, if \f4setnetpath\f1 was not called previously).
|
|
.SH "SEE ALSO"
|
|
\f4netconfig\fP(4), \f4getnetconfig\fP(3N),
|
|
\f4environ\fP(5)
|