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 45.Fn getnetpath 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. 58.Fn getnetpath 59can thus be used to search the netconfig database for all networks 60included in the 61.Ev NETPATH 62variable. 63When 64.Ev NETPATH 65has been exhausted, 66.Fn getnetpath 67returns 68.Dv NULL . 69.Pp 70A call to 71.Fn setnetpath 72.Dq binds 73to or 74.Dq rewinds 75.Ev NETPATH . 76.Fn setnetpath 77must be called before the first call to 78.Fn getnetpath 79and may be called at any other time. 80It returns a handle that is used by 81.Fn getnetpath . 82.Pp 83.Fn getnetpath 84silently ignores invalid 85.Ev NETPATH 86components. 87A 88.Ev NETPATH 89component is invalid if there is no corresponding 90entry in the netconfig database. 91.Pp 92If the 93.Ev NETPATH 94variable is unset, 95.Fn getnetpath 96behaves as if 97.Ev NETPATH 98were set to the sequence of 99.Dq default 100or 101.Dq visible 102networks in the netconfig database, in the 103order in which they are listed. 104.\"This proviso holds also for this 105.\"whole manpage. 106.Pp 107.Fn endnetpath 108may be called to 109.Dq unbind 110from 111.Ev NETPATH 112when processing is complete, releasing resources for reuse. 113Programmers should be aware, however, that 114.Fn endnetpath 115frees all memory allocated by 116.Fn getnetpath 117for the struct netconfig data structure. 118.Sh RETURN VALUES 119.Fn setnetpath 120returns a handle that is used by 121.Fn getnetpath . 122In case of an error, 123.Fn setnetpath 124returns 125.Dv NULL . 126.Pp 127.Fn endnetpath 128returns 0 on success and \-1 on failure 129(for example, if 130.Fn setnetpath 131was not called previously). 132.Fn nc_perror 133or 134.Fn nc_sperror 135can be used to print out the reason for failure. 136See 137.Xr getnetconfig 3 . 138.Pp 139When first called, 140.Fn getnetpath 141returns a pointer to the netconfig database entry corresponding to the first 142valid 143.Ev NETPATH 144component. 145When 146.Ev NETPATH 147has been exhausted, 148.Fn getnetpath 149returns 150.Dv NULL . 151.Sh SEE ALSO 152.Xr getnetconfig 3 , 153.Xr netconfig 5 , 154.Xr environ 7 155