17df0ccbaSfvdl.\" @(#)getnetpath.3n 1.26 93/05/07 SMI; from SVr4 2*e8b12792Suwe.\" $NetBSD: getnetpath.3,v 1.7 2022/12/04 23:02:57 uwe Exp $ 37df0ccbaSfvdl.\" Copyright 1989 AT&T 47df0ccbaSfvdl.Dd April 22, 2000 57df0ccbaSfvdl.Dt GETNETPATH 3 67df0ccbaSfvdl.Os 77df0ccbaSfvdl.Sh NAME 87df0ccbaSfvdl.Nm getnetpath , 97df0ccbaSfvdl.Nm setnetpath , 107df0ccbaSfvdl.Nm endnetpath 117df0ccbaSfvdl.Nd get /etc/netconfig entry corresponding to NETPATH component 127df0ccbaSfvdl.Sh LIBRARY 137df0ccbaSfvdl.Lb libc 147df0ccbaSfvdl.Sh SYNOPSIS 15472351e1Swiz.In netconfig.h 167df0ccbaSfvdl.Ft struct netconfig * 177df0ccbaSfvdl.Fn getnetpath "void *handlep" 187df0ccbaSfvdl.Ft void * 197df0ccbaSfvdl.Fn setnetpath "void" 207df0ccbaSfvdl.Ft int 217df0ccbaSfvdl.Fn endnetpath "void *handlep" 227df0ccbaSfvdl.Sh DESCRIPTION 237df0ccbaSfvdlThe routines described in this page provide the application access to the system 247df0ccbaSfvdlnetwork configuration database, 257df0ccbaSfvdl.Pa /etc/netconfig , 26f51570c5Swizas it is 27f51570c5Swiz.Dq filtered 28*e8b12792Suweby the 29*e8b12792Suwe.Ev NETPATH 30*e8b12792Suweenvironment variable 31*e8b12792Suwe.Po see 32*e8b12792Suwe.Xr environ 7 33*e8b12792Suwe.Pc . 347df0ccbaSfvdlSee 357df0ccbaSfvdl.Xr getnetconfig 3 367df0ccbaSfvdlfor other routines that also access the 377df0ccbaSfvdlnetwork configuration database directly. 38*e8b12792SuweThe 39*e8b12792Suwe.Ev NETPATH 40*e8b12792Suwevariable is a list of colon-separated network identifiers. 417df0ccbaSfvdl.Pp 427df0ccbaSfvdl.Fn getnetpath 437df0ccbaSfvdlreturns a pointer to the 447df0ccbaSfvdlnetconfig database entry corresponding to the first valid 45*e8b12792Suwe.Ev NETPATH 46*e8b12792Suwecomponent. 47*e8b12792SuweThe netconfig entry is formatted as a 48*e8b12792Suwe.Vt struct netconfig . 497df0ccbaSfvdlOn each subsequent call, 507df0ccbaSfvdl.Fn getnetpath 517df0ccbaSfvdlreturns a pointer to the netconfig entry that corresponds to the next 52*e8b12792Suwevalid 53*e8b12792Suwe.Ev NETPATH 54*e8b12792Suwecomponent. 557df0ccbaSfvdl.Fn getnetpath 567df0ccbaSfvdlcan thus be used to search the netconfig database for all networks 57*e8b12792Suweincluded in the 58*e8b12792Suwe.Ev NETPATH 59*e8b12792Suwevariable. 60*e8b12792SuweWhen 61*e8b12792Suwe.Ev NETPATH 62*e8b12792Suwehas been exhausted, 637df0ccbaSfvdl.Fn getnetpath 64*e8b12792Suwereturns 65*e8b12792Suwe.Dv NULL . 667df0ccbaSfvdl.Pp 677df0ccbaSfvdlA call to 687df0ccbaSfvdl.Fn setnetpath 69f51570c5Swiz.Dq binds 70f51570c5Swizto or 71f51570c5Swiz.Dq rewinds 72*e8b12792Suwe.Ev NETPATH . 737df0ccbaSfvdl.Fn setnetpath 747df0ccbaSfvdlmust be called before the first call to 757df0ccbaSfvdl.Fn getnetpath 766569c5c5Swizand may be called at any other time. 776569c5c5SwizIt returns a handle that is used by 787df0ccbaSfvdl.Fn getnetpath . 797df0ccbaSfvdl.Pp 807df0ccbaSfvdl.Fn getnetpath 81*e8b12792Suwesilently ignores invalid 82*e8b12792Suwe.Ev NETPATH 837df0ccbaSfvdlcomponents. 84*e8b12792SuweA 85*e8b12792Suwe.Ev NETPATH 86*e8b12792Suwecomponent is invalid if there is no corresponding 877df0ccbaSfvdlentry in the netconfig database. 887df0ccbaSfvdl.Pp 89*e8b12792SuweIf the 90*e8b12792Suwe.Ev NETPATH 91*e8b12792Suwevariable is unset, 92f51570c5Swiz.Fn getnetpath 93*e8b12792Suwebehaves as if 94*e8b12792Suwe.Ev NETPATH 957df0ccbaSfvdlwere set to the sequence of 96f51570c5Swiz.Dq default 97f51570c5Swizor 98f51570c5Swiz.Dq visible 99f51570c5Swiznetworks in the netconfig database, in the 1007df0ccbaSfvdlorder in which they are listed. 1017df0ccbaSfvdl.\"This proviso holds also for this 1027df0ccbaSfvdl.\"whole manpage. 1037df0ccbaSfvdl.Pp 1047df0ccbaSfvdl.Fn endnetpath 105f51570c5Swizmay be called to 106f51570c5Swiz.Dq unbind 107*e8b12792Suwefrom 108*e8b12792Suwe.Ev NETPATH 1097df0ccbaSfvdlwhen processing is complete, releasing resources for reuse. 1107df0ccbaSfvdlProgrammers should be aware, however, that 1117df0ccbaSfvdl.Fn endnetpath 1127df0ccbaSfvdlfrees all memory allocated by 1137df0ccbaSfvdl.Fn getnetpath 114*e8b12792Suwefor the 115*e8b12792Suwe.Vt struct netconfig 116*e8b12792Suwedata structure. 1177df0ccbaSfvdl.Sh RETURN VALUES 1187df0ccbaSfvdl.Fn setnetpath 1197df0ccbaSfvdlreturns a handle that is used by 1207df0ccbaSfvdl.Fn getnetpath . 1217df0ccbaSfvdlIn case of an error, 1227df0ccbaSfvdl.Fn setnetpath 123*e8b12792Suwereturns 124*e8b12792Suwe.Dv NULL . 1257df0ccbaSfvdl.Pp 1267df0ccbaSfvdl.Fn endnetpath 127*e8b12792Suwereturns 0 on success and \-1 on failure 128*e8b12792Suwe.Po 129*e8b12792Suwefor example, if 1307df0ccbaSfvdl.Fn setnetpath 131*e8b12792Suwewas not called previously 132*e8b12792Suwe.Pc . 1337df0ccbaSfvdl.Fn nc_perror 1347df0ccbaSfvdlor 1357df0ccbaSfvdl.Fn nc_sperror 1367df0ccbaSfvdlcan be used to print out the reason for failure. 1377df0ccbaSfvdlSee 1387df0ccbaSfvdl.Xr getnetconfig 3 . 1397df0ccbaSfvdl.Pp 1407df0ccbaSfvdlWhen first called, 1417df0ccbaSfvdl.Fn getnetpath 1427df0ccbaSfvdlreturns a pointer to the netconfig database entry corresponding to the first 143*e8b12792Suwevalid 144*e8b12792Suwe.Ev NETPATH 145*e8b12792Suwecomponent. 146*e8b12792SuweWhen 147*e8b12792Suwe.Ev NETPATH 148*e8b12792Suwehas been exhausted, 1497df0ccbaSfvdl.Fn getnetpath 150*e8b12792Suwereturns 151*e8b12792Suwe.Dv NULL . 1527df0ccbaSfvdl.Sh SEE ALSO 1537df0ccbaSfvdl.Xr getnetconfig 3 , 154f51570c5Swiz.Xr netconfig 5 , 155f51570c5Swiz.Xr environ 7 156