1.\" @(#)getnetconfig.3n 1.28 93/06/02 SMI; from SVr4 2.\" $NetBSD: getnetconfig.3,v 1.3 2002/02/07 07:00:23 ross 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.Fd #include \*[Lt]netconfig.h\*[Gt] 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 . 39.Fn getnetconfig 40returns a pointer to the 41current entry in the 42.B netconfig 43database, formatted as a struct netconfig . 44Successive calls will return successive netconfig 45entries in the netconfig database. 46.Fn getnetconfig 47can be used to search the entire netconfig 48file. 49.Fn getnetconfig 50returns 51.Dv NULL 52at the end of the file. 53.I handlep 54is the handle obtained through 55.Fn setnetconfig . 56.Pp 57A call to 58.Fn setnetconfig 59has the effect of ``binding'' to or 60``rewinding'' the netconfig database. 61.Fn setnetconfig 62must be called before the first call to 63.Fn getnetconfig 64and may be called at any other time. 65.Fn setnetconfig 66need not be called before a call to 67.Fn getnetconfigent . 68.Fn setnetconfig 69returns a unique handle to be used by 70.Fn getnetconfig . 71.Pp 72.Fn endnetconfig 73should be called when processing is complete to release resources for reuse. 74.Fa handlep 75is the handle obtained through 76.Fn setnetconfig . 77Programmers should be aware, however, that the last call to 78.Fn endnetconfig 79frees all memory allocated by 80.Fn getnetconfig 81for the 82struct netconfig data structure. 83.Fn endnetconfig 84may not be called before 85.Fn setnetconfig . 86.Pp 87.Fn getnetconfigent 88returns a pointer 89to the netconfig structure corresponding 90to 91.Fa netid . 92It returns 93.Dv NULL 94if 95.Fa netid 96is invalid 97(that is, does not name an entry in the netconfig database). 98.Pp 99.Fn freenetconfigent 100frees the netconfig structure pointed to by 101.Fa netconfigp 102(previously returned by 103.Fn getnetconfigent ) . 104.Pp 105.Fn nc_perror 106prints a message to the standard error indicating why any of the 107above routines failed. 108The message is prepended with the string 109.Fa msg 110and a colon. 111A newline character is appended at the end of the message. 112.Pp 113.Fn nc_sperror 114is similar to 115.Fn nc_perror 116but instead of sending the message 117to the standard error, will return a pointer to a string that 118contains the error message. 119.Pp 120.Fn nc_perror 121and 122.Fn nc_sperror 123can also be used with the 124.SB NETPATH 125access routines defined in 126.Xr getnetpath 3 . 127.Sh RETURN VALUES 128.Fn setnetconfig 129returns a unique handle to be used by 130.Fn getnetconfig . 131In the case of an error, 132.Fn setnetconfig 133returns NULL and 134.Fn nc_perror 135or 136.Fn nc_sperror 137can be used to print the reason for failure. 138.Pp 139.Fn getnetconfig 140returns a pointer to the current entry in the netconfig 141database, formatted as a struct netconfig. 142.Fn getnetconfig 143returns NULL 144at the end of the file, or upon failure. 145.Pp 146.Fn endnetconfig 147returns 0 on success and -1 on failure 148(for example, if 149.Fn setnetconfig 150was not called previously). 151.Pp 152On success, 153.B getnetconfigent(\|) 154returns a pointer to the 155.B struct netconfig 156structure corresponding to 157.IR netid ; 158otherwise it returns NULL. 159.Pp 160.Fn nc_sperror 161returns a pointer to a buffer which contains the error message string. 162This buffer is overwritten on each call. 163In multithreaded applications, this buffer is 164implemented as thread-specific data. 165.Sh FILES 166.Pa /etc/netconfig 167.Sh SEE ALSO 168.Xr getnetpath 3 , 169.Xr netconfig 5 170