1.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4 2.\" $NetBSD: getnetpath.3,v 1.6 2003/04/16 13:34:43 wiz 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.In 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 27.Dq filtered 28by the NETPATH 29environment variable (see 30.Xr environ 7 ) . 31See 32.Xr getnetconfig 3 33for other routines that also access the 34network configuration database directly. 35The NETPATH variable is a list of colon-separated network identifiers. 36.Pp 37.Fn getnetpath 38returns a pointer to the 39netconfig database entry corresponding to the first valid 40NETPATH component. 41The netconfig entry is formatted as a struct netconfig. 42On each subsequent call, 43.Fn getnetpath 44returns a pointer to the netconfig entry that corresponds to the next 45valid NETPATH component. 46.Fn getnetpath 47can thus be used to search the netconfig database for all networks 48included in the NETPATH variable. 49When NETPATH has been exhausted, 50.Fn getnetpath 51returns NULL. 52.Pp 53A call to 54.Fn setnetpath 55.Dq binds 56to or 57.Dq rewinds 58NETPATH. 59.Fn setnetpath 60must be called before the first call to 61.Fn getnetpath 62and may be called at any other time. 63It returns a handle that is used by 64.Fn getnetpath . 65.Pp 66.Fn getnetpath 67silently ignores invalid NETPATH 68components. 69A NETPATH component is invalid if there is no corresponding 70entry in the netconfig database. 71.Pp 72If the NETPATH variable is unset, 73.Fn getnetpath 74behaves as if NETPATH 75were set to the sequence of 76.Dq default 77or 78.Dq visible 79networks in the netconfig database, in the 80order in which they are listed. 81.\"This proviso holds also for this 82.\"whole manpage. 83.Pp 84.Fn endnetpath 85may be called to 86.Dq unbind 87from NETPATH 88when processing is complete, releasing resources for reuse. 89Programmers should be aware, however, that 90.Fn endnetpath 91frees all memory allocated by 92.Fn getnetpath 93for the struct netconfig data structure. 94.Sh RETURN VALUES 95.Fn setnetpath 96returns a handle that is used by 97.Fn getnetpath . 98In case of an error, 99.Fn setnetpath 100returns NULL. 101.Pp 102.Fn endnetpath 103returns 0 on success and -1 on failure 104(for example, if 105.Fn setnetpath 106was not called previously). 107.Fn nc_perror 108or 109.Fn nc_sperror 110can be used to print out the reason for failure. 111See 112.Xr getnetconfig 3 . 113.Pp 114When first called, 115.Fn getnetpath 116returns a pointer to the netconfig database entry corresponding to the first 117valid NETPATH component. 118When NETPATH has been exhausted, 119.Fn getnetpath 120returns NULL. 121.Sh SEE ALSO 122.Xr getnetconfig 3 , 123.Xr netconfig 5 , 124.Xr environ 7 125