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