18360efbdSAlfred Perlstein.\" $NetBSD: getnetconfig.3,v 1.1 2000/06/02 23:11:11 fvdl Exp $ 28360efbdSAlfred Perlstein.\" Copyright 1989 AT&T 38360efbdSAlfred Perlstein.Dd April 22, 2000 48360efbdSAlfred Perlstein.Dt GETNETCONFIG 3 58360efbdSAlfred Perlstein.Os 68360efbdSAlfred Perlstein.Sh NAME 78360efbdSAlfred Perlstein.Nm getnetconfig , 88360efbdSAlfred Perlstein.Nm setnetconfig , 98360efbdSAlfred Perlstein.Nm endnetconfig , 108360efbdSAlfred Perlstein.Nm getnetconfigent , 118360efbdSAlfred Perlstein.Nm freenetconfigent , 128360efbdSAlfred Perlstein.Nm nc_perror , 138360efbdSAlfred Perlstein.Nm nc_sperror 148360efbdSAlfred Perlstein.Nd get network configuration database entry 158360efbdSAlfred Perlstein.Sh LIBRARY 168360efbdSAlfred Perlstein.Lb libc 178360efbdSAlfred Perlstein.Sh SYNOPSIS 1832eef9aeSRuslan Ermilov.In netconfig.h 198360efbdSAlfred Perlstein.Ft "struct netconfig *" 208360efbdSAlfred Perlstein.Fn getnetconfig "void *handlep" 218360efbdSAlfred Perlstein.Ft "void *" 228360efbdSAlfred Perlstein.Fn setnetconfig "void" 238360efbdSAlfred Perlstein.Ft int 248360efbdSAlfred Perlstein.Fn endnetconfig "void *handlep" 258360efbdSAlfred Perlstein.Ft "struct netconfig *" 268360efbdSAlfred Perlstein.Fn getnetconfigent "const char *netid" 278360efbdSAlfred Perlstein.Ft void 288360efbdSAlfred Perlstein.Fn freenetconfigent "struct netconfig *netconfigp" 298360efbdSAlfred Perlstein.Ft void 308360efbdSAlfred Perlstein.Fn nc_perror "const char *msg" 318360efbdSAlfred Perlstein.Ft "char *" 328360efbdSAlfred Perlstein.Fn nc_sperror "void" 338360efbdSAlfred Perlstein.Sh DESCRIPTION 348360efbdSAlfred PerlsteinThe library routines described on this page 358360efbdSAlfred Perlsteinprovide the application access to 368360efbdSAlfred Perlsteinthe system network configuration database, 378360efbdSAlfred Perlstein.Pa /etc/netconfig . 381fae73b1SRuslan ErmilovThe 398360efbdSAlfred Perlstein.Fn getnetconfig 401fae73b1SRuslan Ermilovfunction 418360efbdSAlfred Perlsteinreturns a pointer to the 428360efbdSAlfred Perlsteincurrent entry in the 438360efbdSAlfred Perlsteinnetconfig 448360efbdSAlfred Perlsteindatabase, formatted as a 458360efbdSAlfred Perlstein.Ft "struct netconfig" . 468360efbdSAlfred PerlsteinSuccessive calls will return successive netconfig 478360efbdSAlfred Perlsteinentries in the netconfig database. 481fae73b1SRuslan ErmilovThe 498360efbdSAlfred Perlstein.Fn getnetconfig 501fae73b1SRuslan Ermilovfunction 518360efbdSAlfred Perlsteincan be used to search the entire netconfig 528360efbdSAlfred Perlsteinfile. 531fae73b1SRuslan ErmilovThe 548360efbdSAlfred Perlstein.Fn getnetconfig 551fae73b1SRuslan Ermilovfunction 568360efbdSAlfred Perlsteinreturns 578360efbdSAlfred Perlstein.Dv NULL 588360efbdSAlfred Perlsteinat the end of the file. 592efeeba5SRuslan ErmilovThe 608360efbdSAlfred Perlstein.Fa handlep 612efeeba5SRuslan Ermilovargument 628360efbdSAlfred Perlsteinis the handle obtained through 638360efbdSAlfred Perlstein.Fn setnetconfig . 648360efbdSAlfred Perlstein.Pp 658360efbdSAlfred PerlsteinA call to 668360efbdSAlfred Perlstein.Fn setnetconfig 678360efbdSAlfred Perlsteinhas the effect of 688360efbdSAlfred Perlstein.Dq binding 698360efbdSAlfred Perlsteinto or 708360efbdSAlfred Perlstein.Dq rewinding 718360efbdSAlfred Perlsteinthe netconfig database. 721fae73b1SRuslan ErmilovThe 738360efbdSAlfred Perlstein.Fn setnetconfig 741fae73b1SRuslan Ermilovfunction 758360efbdSAlfred Perlsteinmust be called before the first call to 768360efbdSAlfred Perlstein.Fn getnetconfig 778360efbdSAlfred Perlsteinand may be called at any other time. 781fae73b1SRuslan ErmilovThe 798360efbdSAlfred Perlstein.Fn setnetconfig 801fae73b1SRuslan Ermilovfunction 818360efbdSAlfred Perlsteinneed not be called before a call to 828360efbdSAlfred Perlstein.Fn getnetconfigent . 831fae73b1SRuslan ErmilovThe 848360efbdSAlfred Perlstein.Fn setnetconfig 851fae73b1SRuslan Ermilovfunction 868360efbdSAlfred Perlsteinreturns a unique handle to be used by 878360efbdSAlfred Perlstein.Fn getnetconfig . 888360efbdSAlfred Perlstein.Pp 891fae73b1SRuslan ErmilovThe 908360efbdSAlfred Perlstein.Fn endnetconfig 911fae73b1SRuslan Ermilovfunction 928360efbdSAlfred Perlsteinshould be called when processing is complete to release resources for reuse. 932efeeba5SRuslan ErmilovThe 948360efbdSAlfred Perlstein.Fa handlep 952efeeba5SRuslan Ermilovargument 968360efbdSAlfred Perlsteinis the handle obtained through 978360efbdSAlfred Perlstein.Fn setnetconfig . 988360efbdSAlfred PerlsteinProgrammers should be aware, however, that the last call to 998360efbdSAlfred Perlstein.Fn endnetconfig 1008360efbdSAlfred Perlsteinfrees all memory allocated by 1018360efbdSAlfred Perlstein.Fn getnetconfig 1028360efbdSAlfred Perlsteinfor the 1038360efbdSAlfred Perlstein.Ft "struct netconfig" 1048360efbdSAlfred Perlsteindata structure. 1051fae73b1SRuslan ErmilovThe 1068360efbdSAlfred Perlstein.Fn endnetconfig 1071fae73b1SRuslan Ermilovfunction 1088360efbdSAlfred Perlsteinmay not be called before 1098360efbdSAlfred Perlstein.Fn setnetconfig . 1108360efbdSAlfred Perlstein.Pp 1111fae73b1SRuslan ErmilovThe 1128360efbdSAlfred Perlstein.Fn getnetconfigent 1131fae73b1SRuslan Ermilovfunction 1148360efbdSAlfred Perlsteinreturns a pointer 1158360efbdSAlfred Perlsteinto the netconfig structure corresponding 1168360efbdSAlfred Perlsteinto 1178360efbdSAlfred Perlstein.Fa netid . 1188360efbdSAlfred PerlsteinIt returns 1198360efbdSAlfred Perlstein.Dv NULL 1208360efbdSAlfred Perlsteinif 1218360efbdSAlfred Perlstein.Fa netid 1228360efbdSAlfred Perlsteinis invalid 1238360efbdSAlfred Perlstein(that is, does not name an entry in the netconfig database). 1248360efbdSAlfred Perlstein.Pp 1251fae73b1SRuslan ErmilovThe 1268360efbdSAlfred Perlstein.Fn freenetconfigent 1271fae73b1SRuslan Ermilovfunction 1288360efbdSAlfred Perlsteinfrees the netconfig structure pointed to by 1298360efbdSAlfred Perlstein.Fa netconfigp 1308360efbdSAlfred Perlstein(previously returned by 1318360efbdSAlfred Perlstein.Fn getnetconfigent ) . 1328360efbdSAlfred Perlstein.Pp 1331fae73b1SRuslan ErmilovThe 1348360efbdSAlfred Perlstein.Fn nc_perror 1351fae73b1SRuslan Ermilovfunction 1368360efbdSAlfred Perlsteinprints a message to the standard error indicating why any of the 1378360efbdSAlfred Perlsteinabove routines failed. 1388360efbdSAlfred PerlsteinThe message is prepended with the string 1398360efbdSAlfred Perlstein.Fa msg 1408360efbdSAlfred Perlsteinand a colon. 1418360efbdSAlfred PerlsteinA newline character is appended at the end of the message. 1428360efbdSAlfred Perlstein.Pp 1431fae73b1SRuslan ErmilovThe 1448360efbdSAlfred Perlstein.Fn nc_sperror 1451fae73b1SRuslan Ermilovfunction 1468360efbdSAlfred Perlsteinis similar to 1478360efbdSAlfred Perlstein.Fn nc_perror 1488360efbdSAlfred Perlsteinbut instead of sending the message 1498360efbdSAlfred Perlsteinto the standard error, will return a pointer to a string that 1508360efbdSAlfred Perlsteincontains the error message. 1518360efbdSAlfred Perlstein.Pp 1521fae73b1SRuslan ErmilovThe 1538360efbdSAlfred Perlstein.Fn nc_perror 1548360efbdSAlfred Perlsteinand 1558360efbdSAlfred Perlstein.Fn nc_sperror 1561fae73b1SRuslan Ermilovfunctions 1578360efbdSAlfred Perlsteincan also be used with the 1588360efbdSAlfred Perlstein.Ev NETPATH 1598360efbdSAlfred Perlsteinaccess routines defined in 1608360efbdSAlfred Perlstein.Xr getnetpath 3 . 1618360efbdSAlfred Perlstein.Sh RETURN VALUES 1621fae73b1SRuslan ErmilovThe 1638360efbdSAlfred Perlstein.Fn setnetconfig 1641fae73b1SRuslan Ermilovfunction 1658360efbdSAlfred Perlsteinreturns a unique handle to be used by 1668360efbdSAlfred Perlstein.Fn getnetconfig . 1678360efbdSAlfred PerlsteinIn the case of an error, 1688360efbdSAlfred Perlstein.Fn setnetconfig 1698360efbdSAlfred Perlsteinreturns 1708360efbdSAlfred Perlstein.Dv NULL 1718360efbdSAlfred Perlsteinand 1728360efbdSAlfred Perlstein.Fn nc_perror 1738360efbdSAlfred Perlsteinor 1748360efbdSAlfred Perlstein.Fn nc_sperror 1758360efbdSAlfred Perlsteincan be used to print the reason for failure. 1768360efbdSAlfred Perlstein.Pp 1771fae73b1SRuslan ErmilovThe 1788360efbdSAlfred Perlstein.Fn getnetconfig 1791fae73b1SRuslan Ermilovfunction 1808360efbdSAlfred Perlsteinreturns a pointer to the current entry in the netconfig 1818360efbdSAlfred Perlsteindatabase, formatted as a 1828360efbdSAlfred Perlstein.Ft "struct netconfig" . 1831fae73b1SRuslan ErmilovThe 1848360efbdSAlfred Perlstein.Fn getnetconfig 1851fae73b1SRuslan Ermilovfunction 1868360efbdSAlfred Perlsteinreturns 1878360efbdSAlfred Perlstein.Dv NULL 1888360efbdSAlfred Perlsteinat the end of the file, or upon failure. 1898360efbdSAlfred Perlstein.Pp 1901fae73b1SRuslan ErmilovThe 1918360efbdSAlfred Perlstein.Fn endnetconfig 1921fae73b1SRuslan Ermilovfunction 1938360efbdSAlfred Perlsteinreturns 0 on success and \-1 on failure 1948360efbdSAlfred Perlstein(for example, if 1958360efbdSAlfred Perlstein.Fn setnetconfig 1968360efbdSAlfred Perlsteinwas not called previously). 1978360efbdSAlfred Perlstein.Pp 1988360efbdSAlfred PerlsteinOn success, 1998360efbdSAlfred Perlstein.Fn getnetconfigent 2008360efbdSAlfred Perlsteinreturns a pointer to the 2018360efbdSAlfred Perlstein.Ft "struct netconfig" 2028360efbdSAlfred Perlsteinstructure corresponding to 2038360efbdSAlfred Perlstein.Fa netid ; 2048360efbdSAlfred Perlsteinotherwise it returns 2058360efbdSAlfred Perlstein.Dv NULL . 2068360efbdSAlfred Perlstein.Pp 2071fae73b1SRuslan ErmilovThe 2088360efbdSAlfred Perlstein.Fn nc_sperror 2091fae73b1SRuslan Ermilovfunction 2108360efbdSAlfred Perlsteinreturns a pointer to a buffer which contains the error message string. 2118360efbdSAlfred PerlsteinThis buffer is overwritten on each call. 2128360efbdSAlfred PerlsteinIn multithreaded applications, this buffer is 2138360efbdSAlfred Perlsteinimplemented as thread-specific data. 2148360efbdSAlfred Perlstein.Sh FILES 2158360efbdSAlfred Perlstein.Bl -tag -width /etc/netconfig -compact 2168360efbdSAlfred Perlstein.It Pa /etc/netconfig 2178360efbdSAlfred Perlstein.El 2188360efbdSAlfred Perlstein.Sh SEE ALSO 2198360efbdSAlfred Perlstein.Xr getnetpath 3 , 2208360efbdSAlfred Perlstein.Xr netconfig 5 221