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