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