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