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