.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4

.\" Copyright 1989 AT&T

.Dd April 22, 2000

.Dt GETNETPATH 3

.Os

.Sh NAME

.Nm getnetpath ,

.Nm setnetpath ,

.Nm endnetpath

.Nd get

.Pa /etc/netconfig

entry corresponding to

.Ev NETPATH

component

.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

.Ev NETPATH

environment variable (see

.Xr environ 7 ) .

See

.Xr getnetconfig 3

for other routines that also access the

network configuration database directly.

The

.Ev NETPATH

variable is a list of colon-separated network identifiers.

.Pp

The

.Fn getnetpath

function

returns a pointer to the

netconfig database entry corresponding to the first valid

.Ev NETPATH

component.

The netconfig entry is formatted as a

.Ft "struct netconfig" .

On each subsequent call,

.Fn getnetpath

returns a pointer to the netconfig entry that corresponds to the next

valid

.Ev NETPATH

component.

The

.Fn getnetpath

function

can thus be used to search the netconfig database for all networks

included in the

.Ev NETPATH

variable.

When

.Ev NETPATH

has been exhausted,

.Fn getnetpath

returns

.Dv NULL .

.Pp

A call to

.Fn setnetpath

.Dq binds

to or

.Dq rewinds

.Ev NETPATH .

The

.Fn setnetpath

function

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

The

.Fn getnetpath

function

silently ignores invalid

.Ev NETPATH

components.

A

.Ev NETPATH

component is invalid if there is no corresponding

entry in the netconfig database.

.Pp

If the

.Ev NETPATH

variable is unset,

.Fn getnetpath

behaves as if

.Ev 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

The

.Fn endnetpath

function

may be called to

.Dq unbind

from

.Ev 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

The

.Fn setnetpath

function

returns a handle that is used by

.Fn getnetpath .

In case of an error,

.Fn setnetpath

returns

.Dv NULL .

.Pp

The

.Fn endnetpath

function

returns 0 on success and \-1 on failure

(for example, if

.Fn setnetpath

was not called previously).

The

.Fn nc_perror

or

.Fn nc_sperror

function

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

.Ev NETPATH

component.

When

.Ev NETPATH

has been exhausted,

.Fn getnetpath

returns

.Dv NULL .

.Sh AVAILABILITY

These functions are part of libtirpc.

.Sh SEE ALSO

.Xr getnetconfig 3 ,

.Xr netconfig 5 ,

.Xr environ 7