| .\" @(#)getnetconfig.3n 1.28 93/06/02 SMI; from SVr4 |
| .\" Copyright 1989 AT&T |
| .Dd April 22, 2000 |
| .Dt GETNETCONFIG 3 |
| .Os |
| .Sh NAME |
| .Nm getnetconfig , |
| .Nm setnetconfig , |
| .Nm endnetconfig , |
| .Nm getnetconfigent , |
| .Nm freenetconfigent , |
| .Nm nc_perror , |
| .Nm nc_sperror |
| .Nd get network configuration database entry |
| .Sh LIBRARY |
| .Lb libc |
| .Sh SYNOPSIS |
| .In netconfig.h |
| .Ft "struct netconfig *" |
| .Fn getnetconfig "void *handlep" |
| .Ft "void *" |
| .Fn setnetconfig "void" |
| .Ft int |
| .Fn endnetconfig "void *handlep" |
| .Ft "struct netconfig *" |
| .Fn getnetconfigent "const char *netid" |
| .Ft void |
| .Fn freenetconfigent "struct netconfig *netconfigp" |
| .Ft void |
| .Fn nc_perror "const char *msg" |
| .Ft "char *" |
| .Fn nc_sperror "void" |
| .Sh DESCRIPTION |
| The library routines described on this page |
| provide the application access to |
| the system network configuration database, |
| .Pa /etc/netconfig . |
| The |
| .Fn getnetconfig |
| function |
| returns a pointer to the |
| current entry in the |
| netconfig |
| database, formatted as a |
| .Ft "struct netconfig" . |
| Successive calls will return successive netconfig |
| entries in the netconfig database. |
| The |
| .Fn getnetconfig |
| function |
| can be used to search the entire netconfig |
| file. |
| The |
| .Fn getnetconfig |
| function |
| returns |
| .Dv NULL |
| at the end of the file. |
| The |
| .Fa handlep |
| argument |
| is the handle obtained through |
| .Fn setnetconfig . |
| .Pp |
| A call to |
| .Fn setnetconfig |
| has the effect of |
| .Dq binding |
| to or |
| .Dq rewinding |
| the netconfig database. |
| The |
| .Fn setnetconfig |
| function |
| must be called before the first call to |
| .Fn getnetconfig |
| and may be called at any other time. |
| The |
| .Fn setnetconfig |
| function |
| need not be called before a call to |
| .Fn getnetconfigent . |
| The |
| .Fn setnetconfig |
| function |
| returns a unique handle to be used by |
| .Fn getnetconfig . |
| .Pp |
| The |
| .Fn endnetconfig |
| function |
| should be called when processing is complete to release resources for reuse. |
| The |
| .Fa handlep |
| argument |
| is the handle obtained through |
| .Fn setnetconfig . |
| Programmers should be aware, however, that the last call to |
| .Fn endnetconfig |
| frees all memory allocated by |
| .Fn getnetconfig |
| for the |
| .Ft "struct netconfig" |
| data structure. |
| The |
| .Fn endnetconfig |
| function |
| may not be called before |
| .Fn setnetconfig . |
| .Pp |
| The |
| .Fn getnetconfigent |
| function |
| returns a pointer |
| to the netconfig structure corresponding |
| to |
| .Fa netid . |
| It returns |
| .Dv NULL |
| if |
| .Fa netid |
| is invalid |
| (that is, does not name an entry in the netconfig database). |
| .Pp |
| The |
| .Fn freenetconfigent |
| function |
| frees the netconfig structure pointed to by |
| .Fa netconfigp |
| (previously returned by |
| .Fn getnetconfigent ) . |
| .Pp |
| The |
| .Fn nc_perror |
| function |
| prints a message to the standard error indicating why any of the |
| above routines failed. |
| The message is prepended with the string |
| .Fa msg |
| and a colon. |
| A newline character is appended at the end of the message. |
| .Pp |
| The |
| .Fn nc_sperror |
| function |
| is similar to |
| .Fn nc_perror |
| but instead of sending the message |
| to the standard error, will return a pointer to a string that |
| contains the error message. |
| .Pp |
| The |
| .Fn nc_perror |
| and |
| .Fn nc_sperror |
| functions |
| can also be used with the |
| .Ev NETPATH |
| access routines defined in |
| .Xr getnetpath 3 . |
| .Sh RETURN VALUES |
| The |
| .Fn setnetconfig |
| function |
| returns a unique handle to be used by |
| .Fn getnetconfig . |
| In the case of an error, |
| .Fn setnetconfig |
| returns |
| .Dv NULL |
| and |
| .Fn nc_perror |
| or |
| .Fn nc_sperror |
| can be used to print the reason for failure. |
| .Pp |
| The |
| .Fn getnetconfig |
| function |
| returns a pointer to the current entry in the netconfig |
| database, formatted as a |
| .Ft "struct netconfig" . |
| The |
| .Fn getnetconfig |
| function |
| returns |
| .Dv NULL |
| at the end of the file, or upon failure. |
| .Pp |
| The |
| .Fn endnetconfig |
| function |
| returns 0 on success and \-1 on failure |
| (for example, if |
| .Fn setnetconfig |
| was not called previously). |
| .Pp |
| On success, |
| .Fn getnetconfigent |
| returns a pointer to the |
| .Ft "struct netconfig" |
| structure corresponding to |
| .Fa netid ; |
| otherwise it returns |
| .Dv NULL . |
| .Pp |
| The |
| .Fn nc_sperror |
| function |
| returns a pointer to a buffer which contains the error message string. |
| This buffer is overwritten on each call. |
| In multithreaded applications, this buffer is |
| implemented as thread-specific data. |
| .Sh FILES |
| .Bl -tag -width /etc/netconfig -compact |
| .It Pa /etc/netconfig |
| .El |
| .Sh SEE ALSO |
| .Xr getnetpath 3 , |
| .Xr netconfig 5 |