1.\" $NetBSD: getnetconfig.3,v 1.1 2000/06/02 23:11:11 fvdl Exp $ 2.\" Copyright 1989 AT&T 3.Dd April 22, 2000 4.Dt GETNETCONFIG 3 5.Os 6.Sh NAME 7.Nm getnetconfig , 8.Nm setnetconfig , 9.Nm endnetconfig , 10.Nm getnetconfigent , 11.Nm freenetconfigent , 12.Nm nc_perror , 13.Nm nc_sperror 14.Nd get network configuration database entry 15.Sh LIBRARY 16.Lb libc 17.Sh SYNOPSIS 18.In netconfig.h 19.Ft "struct netconfig *" 20.Fn getnetconfig "void *handlep" 21.Ft "void *" 22.Fn setnetconfig "void" 23.Ft int 24.Fn endnetconfig "void *handlep" 25.Ft "struct netconfig *" 26.Fn getnetconfigent "const char *netid" 27.Ft void 28.Fn freenetconfigent "struct netconfig *netconfigp" 29.Ft void 30.Fn nc_perror "const char *msg" 31.Ft "char *" 32.Fn nc_sperror "void" 33.Sh DESCRIPTION 34The library routines described on this page 35provide the application access to 36the system network configuration database, 37.Pa /etc/netconfig . 38The 39.Fn getnetconfig 40function 41returns a pointer to the 42current entry in the 43netconfig 44database, formatted as a 45.Ft "struct netconfig" . 46Successive calls will return successive netconfig 47entries in the netconfig database. 48The 49.Fn getnetconfig 50function 51can be used to search the entire netconfig 52file. 53The 54.Fn getnetconfig 55function 56returns 57.Dv NULL 58at the end of the file. 59The 60.Fa handlep 61argument 62is the handle obtained through 63.Fn setnetconfig . 64.Pp 65A call to 66.Fn setnetconfig 67has the effect of 68.Dq binding 69to or 70.Dq rewinding 71the netconfig database. 72The 73.Fn setnetconfig 74function 75must be called before the first call to 76.Fn getnetconfig 77and may be called at any other time. 78The 79.Fn setnetconfig 80function 81need not be called before a call to 82.Fn getnetconfigent . 83The 84.Fn setnetconfig 85function 86returns a unique handle to be used by 87.Fn getnetconfig . 88.Pp 89The 90.Fn endnetconfig 91function 92should be called when processing is complete to release resources for reuse. 93The 94.Fa handlep 95argument 96is the handle obtained through 97.Fn setnetconfig . 98Programmers should be aware, however, that the last call to 99.Fn endnetconfig 100frees all memory allocated by 101.Fn getnetconfig 102for the 103.Ft "struct netconfig" 104data structure. 105The 106.Fn endnetconfig 107function 108may not be called before 109.Fn setnetconfig . 110.Pp 111The 112.Fn getnetconfigent 113function 114returns a pointer 115to the netconfig structure corresponding 116to 117.Fa netid . 118It returns 119.Dv NULL 120if 121.Fa netid 122is invalid 123(that is, does not name an entry in the netconfig database). 124.Pp 125The 126.Fn freenetconfigent 127function 128frees the netconfig structure pointed to by 129.Fa netconfigp 130(previously returned by 131.Fn getnetconfigent ) . 132.Pp 133The 134.Fn nc_perror 135function 136prints a message to the standard error indicating why any of the 137above routines failed. 138The message is prepended with the string 139.Fa msg 140and a colon. 141A newline character is appended at the end of the message. 142.Pp 143The 144.Fn nc_sperror 145function 146is similar to 147.Fn nc_perror 148but instead of sending the message 149to the standard error, will return a pointer to a string that 150contains the error message. 151.Pp 152The 153.Fn nc_perror 154and 155.Fn nc_sperror 156functions 157can also be used with the 158.Ev NETPATH 159access routines defined in 160.Xr getnetpath 3 . 161.Sh RETURN VALUES 162The 163.Fn setnetconfig 164function 165returns a unique handle to be used by 166.Fn getnetconfig . 167In the case of an error, 168.Fn setnetconfig 169returns 170.Dv NULL 171and 172.Fn nc_perror 173or 174.Fn nc_sperror 175can be used to print the reason for failure. 176.Pp 177The 178.Fn getnetconfig 179function 180returns a pointer to the current entry in the netconfig 181database, formatted as a 182.Ft "struct netconfig" . 183The 184.Fn getnetconfig 185function 186returns 187.Dv NULL 188at the end of the file, or upon failure. 189.Pp 190The 191.Fn endnetconfig 192function 193returns 0 on success and \-1 on failure 194(for example, if 195.Fn setnetconfig 196was not called previously). 197.Pp 198On success, 199.Fn getnetconfigent 200returns a pointer to the 201.Ft "struct netconfig" 202structure corresponding to 203.Fa netid ; 204otherwise it returns 205.Dv NULL . 206.Pp 207The 208.Fn nc_sperror 209function 210returns a pointer to a buffer which contains the error message string. 211This buffer is overwritten on each call. 212In multithreaded applications, this buffer is 213implemented as thread-specific data. 214.Sh FILES 215.Bl -tag -width /etc/netconfig -compact 216.It Pa /etc/netconfig 217.El 218.Sh SEE ALSO 219.Xr getnetpath 3 , 220.Xr netconfig 5 221