1.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4 2.\" $NetBSD: getnetpath.3,v 1.3 2002/02/07 07:00:23 ross 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 \*[Lt]netconfig.h\*[Gt] 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. It returns a handle that is used by 63.Fn getnetpath . 64.Pp 65.Fn getnetpath 66silently ignores invalid NETPATH 67components. 68A NETPATH component is invalid if there is no corresponding 69entry in the netconfig database. 70.Pp 71If the NETPATH variable is unset, 72.Fn getnetpath 73behaves as if NETPATH 74were set to the sequence of 75.Dq default 76or 77.Dq visible 78networks in the netconfig database, in the 79order in which they are listed. 80.\"This proviso holds also for this 81.\"whole manpage. 82.Pp 83.Fn endnetpath 84may be called to 85.Dq unbind 86from NETPATH 87when processing is complete, releasing resources for reuse. 88Programmers should be aware, however, that 89.Fn endnetpath 90frees all memory allocated by 91.Fn getnetpath 92for the struct netconfig data structure. 93.Sh RETURN VALUES 94.Fn setnetpath 95returns a handle that is used by 96.Fn getnetpath . 97In case of an error, 98.Fn setnetpath 99returns NULL. 100.Pp 101.Fn endnetpath 102returns 0 on success and -1 on failure 103(for example, if 104.Fn setnetpath 105was not called previously). 106.Fn nc_perror 107or 108.Fn nc_sperror 109can be used to print out the reason for failure. 110See 111.Xr getnetconfig 3 . 112.Pp 113When first called, 114.Fn getnetpath 115returns a pointer to the netconfig database entry corresponding to the first 116valid NETPATH component. When NETPATH has been exhausted, 117.Fn getnetpath 118returns NULL. 119.Sh SEE ALSO 120.Xr getnetconfig 3 , 121.Xr netconfig 5 , 122.Xr environ 7 123