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