'\"macro stdmacro
.if n .pH g3n.getnetpath @(#)getnetpath	40.12 of 12/12/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} getnetpath 3N "Networking Services Architecture" "\&"
.if \nX=1 .ds x} getnetpath 3N "Networking Services Architecture"
.if \nX=2 .ds x} getnetpath 3N "" "\&"
.if \nX=3 .ds x} getnetpath "" "" "\&"
.TH \*(x}
.SH NAME
\f4getnetpath\f1 \- get /etc/netconfig entry corresponding to \f4NETPATH\f1 component
.SH "SYNOPSIS"
.nf
\f4#include <netconfig.h>
.sp .5
void *
setnetpath()
.sp .5
struct netconfig *
getnetpath(handlep);
void * handlep;
.sp .5
int
endnetpath(handlep);
void * handlep;\f1
.fi
.SH "DESCRIPTION"
The three routines described on this page are
part of the \s-1UNIX\s+1 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(CWstruct netconfig\f1.
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
\s-1NULL\s+1.
.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 \f2unset\f1, \f4getnetpath()\f1
behaves \f2as if\f1 \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()\fP frees all
memory allocated by \f4setnetpath()\fP.
\f4endnetpath()\fP returns \f40\f1 on success and \f4\-1\f1 on failure
(e.g., if \f4setnetpath()\f1 was not called previously).
.SH "SEE ALSO"
\f4netconfig\fP(4), \f4getnetconfig\fP(3N), \f4environ\fP(5)
.br
\f2Network Programmer's Guide\f1
.br
\f2System Administrator's Guide\f1
