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