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