1.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4 2.\" $NetBSD: getnetpath.3,v 1.1 2000/06/02 23:11:11 fvdl Exp $ 3.\" Copyright 1989 AT&T 4.Dd April 22, 2000 5.Dt GETNETPATH 3 6.Os 7.Sh NAME 8.Nm getnetpath , 9.Nm setnetpath , 10.Nm endnetpath 11.Nd get /etc/netconfig entry corresponding to NETPATH component 12.Sh LIBRARY 13.Lb libc 14.Sh SYNOPSIS 15.Fd #include <netconfig.h> 16.Ft struct netconfig * 17.Fn getnetpath "void *handlep" 18.Ft void * 19.Fn setnetpath "void" 20.Ft int 21.Fn endnetpath "void *handlep" 22.Sh DESCRIPTION 23The routines described in this page provide the application access to the system 24network configuration database, 25.Pa /etc/netconfig , 26as it is ``filtered'' by the NETPATH 27environment variable (see 28.Xr environ 5 ). 29See 30.Xr getnetconfig 3 31for other routines that also access the 32network configuration database directly. 33The NETPATH variable is a list of colon-separated network identifiers. 34.Pp 35.Fn getnetpath 36returns a pointer to the 37netconfig database entry corresponding to the first valid 38NETPATH component. 39The netconfig entry is formatted as a struct netconfig. 40On each subsequent call, 41.Fn getnetpath 42returns a pointer to the netconfig entry that corresponds to the next 43valid NETPATH component. 44.Fn getnetpath 45can thus be used to search the netconfig database for all networks 46included in the NETPATH variable. 47When NETPATH has been exhausted, 48.Fn getnetpath 49returns NULL. 50.Pp 51A call to 52.Fn setnetpath 53``binds'' to or ``rewinds'' NETPATH. 54.Fn setnetpath 55must be called before the first call to 56.Fn getnetpath 57and may be called at any other time. It returns a handle that is used by 58.Fn getnetpath . 59.Pp 60.Fn getnetpath 61silently ignores invalid NETPATH 62components. 63A NETPATH component is invalid if there is no corresponding 64entry in the netconfig database. 65.Pp 66If the NETPATH variable is unset, 67.Fn getnetpath(\|) 68behaves as if NETPATH 69were set to the sequence of 70``default'' or ``visible'' networks in the netconfig database, in the 71order in which they are listed. 72.\"This proviso holds also for this 73.\"whole manpage. 74.Pp 75.Fn endnetpath 76may be called to ``unbind'' from NETPATH 77when processing is complete, releasing resources for reuse. 78Programmers should be aware, however, that 79.Fn endnetpath 80frees all memory allocated by 81.Fn getnetpath 82for the struct netconfig data structure. 83.Sh RETURN VALUES 84.Fn setnetpath 85returns a handle that is used by 86.Fn getnetpath . 87In case of an error, 88.Fn setnetpath 89returns NULL. 90.Pp 91.Fn endnetpath 92returns 0 on success and -1 on failure 93(for example, if 94.Fn setnetpath 95was not called previously). 96.Fn nc_perror 97or 98.Fn nc_sperror 99can be used to print out the reason for failure. 100See 101.Xr getnetconfig 3 . 102.Pp 103When first called, 104.Fn getnetpath 105returns a pointer to the netconfig database entry corresponding to the first 106valid NETPATH component. When NETPATH has been exhausted, 107.Fn getnetpath 108returns NULL. 109.Sh SEE ALSO 110.Xr getnetconfig 3 , 111.Xr netconfig 4 , 112.Xr environ 5 113