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