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