NETCONFIG

Section: OpenSS7 STREAMS Network Services Library Library Calls (3)
Updated: 2008-10-31
Index Return to Main Contents

NAME

netconfig, netselect, setnetconfig, getnetconfig, endnetconfig, getnetconfigent, freenetconfigent, nc_perror, nc_sperror - Network Configuration database subroutines.

SYNOPSIS

#include <netconfig.h>
void *setnetconfig(void);
struct netconfig *getnetconfig(void *handle);
int endnetconfig(void *handle);
struct netconfig *getnetconfigent(const char *netid);
void freenetconfigent(struct netconfig *netconfig);
void nc_perror(const char *msg);
char *nc_sperror(void);

ARGUMENTS

handle: an opaque pointer returned by setnetconfig() to be used as an argument to calls to getnetconfig().
netid: A network identifier string. This should match one of the network identifier strings from the netconfig(5) file.
netconfig: A pointer to a netconfig structure returned from getnetconfigent() to be freed by freenetconfigent().
msg: A short message string to prefix to the error message printed to standard error by the nc_perror() subroutine.

DESCRIPTION

UNIX® has traditionally provided three components of the Network Services Library, libnsl, that are associated with Transport Provider Interface, tpi(7), STREAMS(9) network pseudo-device drivers, and that are not currently part of the Linux Network Services Library. These components are:

1.: Network Configuration database access, see netconfig(3).
2.: Network Directory and address mapping, see netdir(3).
3.: Network Path access, see netpath(3).

These are often refered to as the Network Selection facility of the Network Services Library.

setnetconfig(), getnetconfig(), endnetconfig(), getnetconfigent(), freenetconfigent(), nc_perror() and nc_sperror(), provide a set of Network Configuration database access subroutines for accessing the Network Configuration database contained in the /etc/netconfig, netconfig(5), file.

setnetconfig(), getnetconfig() and endnetconfig(), provide a mechanism to sequentially access each entry in the Network Configuration database.

setnetconfig(): returns a pointer to an opaque datastructure used as a handle to the getnetconfig() subroutine. setnetconfig() is used to initialize client access to the database entries and set the access point to the first entry.
getnetconfig(),: when called successively with the handle returned by the call to setnetconfig(), returns each Network Configuration database entry starting with the first. When no additional entries remain that have not already been retreived since the call to setnetconfig(), getnetconfig() returns a NULL pointer to indicate that the end of the database has been reached.
endnetconfig(): releases client access to the database and frees for reuse any resources that were held by setnetconfig() for use by getnetconfig(). endnetconfig() must only be called with a handle returned from a previous and corresponding call to setnetconfig(). endnetconfig() must be called for each call to setnetconfig() with the corresponding handle pointer as the argument.

getnetconfigent() and freenetconfigent() provide a mechanism to access Network Configuration database entries by network identification name strings.

getnetconfigent(): Returns a pointer to the netconfig structure corresponding to the network configuration entry with the same network identification name as that supplied in the netid argument.
freenetconfigent(): frees the network configuration entry returned as a pointer to a netconfig structure, from a previous call to getnetconfigent(). freenetconfigent() must be called for each call to getnetconfigent() with the corresponding netconfig pointer as the argument.

nc_perror() and nc_sperror() provide a mechanism for providing diagnostic messages upon failure. These subroutines can be used both for these netconfig subroutines, as well as netpath(3) subroutines.

nc_perror(): prints a diagnostic message to standard error with the string provided in the msg argument used as a prefix followed by a colon. Diagnostic messages printed to standard error are followed with a NEWLINE.
nc_sperror(): is similar to nc_perror(), but, instead of printing the message to standard error, only a pointer to the diagnostic message string is returned. This allows the caller to subsequently format and store a message according to the caller's specifications.

FILE FORMAT

The format of the /etc/netconfig Network Configuration database file is as described in netconfig(5).

DATABASE STRUCTURE

The netconfig structure is defined in <netconfig.h> as follows:

struct netconfig {
    char *nc_netid;      /* network id string */
    ulong nc_semantics;  /* service interface semantics */
    ulong nc_flag;       /* flags */
    char *nc_protofmly;  /* protocol family string */
    char *nc_proto;      /* protocol name string */
    char *nc_device;     /* STREAMS device path */
    ulong nc_nlookups;   /* num. of name-to-address libs */
    char **nc_lookups;   /* name-to-address libraries */
    ulong nc_unused[9];  /* reserved for future use */
};

Where the members of the netconfig structure are as follows:

nc_netid

The network identifier string defined by the system administrator and unique to each entry in the network configuration database file.

nc_semantics

The semantics describing the service interface of the associated STREAMS transport service provider. nc_semantics can take on one of the following values:

NC_TPI_CLTS: Transport Provider interface, tpi(7), Connectionless Transport Service.
NC_TPI_COTS: Transport Provider interface, tpi(7), Connection-Oriented Transport Service.
NC_TPI_COTS_ORD: Transport Provider interface, tpi(7), Connection-Oriented Transport Service with Orderly Release.
NC_TPI_RAW: Transport Provider interface, tpi(7), Raw Transport Service.

nc_flag

Flags associated with the transport entry. nc_flag can take on one of the following values:

NC_NOFLAG: No option flag is indicated.
NC_VISIBLE: The visible option flag is indicated. This means that the network transport provider is visible to getpath(3) when the NETPATH environment variable is not set.
NC_BROADCAST: The broadcast option flag is indicated. This means that the network transport provider supports broadcast addresses, and in particular, the HOST_BROADCAST universal address described in netdir_getbyname(3).
NC_MULTICAST: The multicast option flag is indicated. This means that the network transport provider supports multicast addresses, and in particular, the HOST_ALLNODES and HOST_RPCNODES universal addresses described in netdir_getbyname(3).

nc_protofmly

The protocol family string assigned by the system adminstrator.

nc_proto

The protocol string assigned by the system administrator.

nc_device

The device path to a STREAMS clone(4) device that provides access to the associated transport provider.

nc_nlookups

The number of name to address translation libraries.

nc_lookups

An array of address translation libraries. The number of strings contained in this array is specified with the nc_nlookups field.

nc_unused

Unused bytes reserved for future expansion.

NOTICES

nc_perror() and nc_sperror() must be called immediately after the failed network configuration subroutine fails. Otherwise, the error condition may be lost.

RETURN VALUE

Upon successful completion, setnetconfig() returns an opaque pointer for use in the getnetconfig() call. Otherwise, NULL is returned and nc_error(3) is set to indicate the error.

Upon successful completion, endnetconfig() returns 0. Otherwise, -1 is returned and nc_error(3) is set to indicate the error. A diagnostic string can be printed to standard error or accesed using the nc_perror() or nc_sperror() subroutines.

Upon successful completion, nc_sperror() returns a pointer to a string describing the error condition. (Note that this subroutine can also be used for netpath(3) subroutines.) Otherwise, NULL is returned.

Upon successful completion, getnetconfig() and getnetconfigent() return a pointer to a netconfig structure. Otherwise, they return NULL to indicate failure.

ERROR HANDLING

When an error occurs, an error message can be printed to standard error or retrieved using nc_perror() or nc_sperror().

ERRORS

The setnetconfig() subroutine will fail, and return a NULL pointer, if: an error was encountered opening the Network Configuration database, /etc/netconfig, see netconfig(5).

The getnetconfig() subroutine will fail, and return a NULL pointer, if: no entries exist in the Network Configuration database; or, the last entry in the Network Configuration database has been read with a previous call to getnetconfig() and there are no more entries in the Network Configuration database.

The endnetconfig() subroutine will fail if: the passed in handle argument is invalid; or, endnetconfig() has already been called for the handle argument.

The passed in handle argument is only invalid when there is not a subsequent, corresponding call to setnetconfig().

The getnetconfigent() subroutine will fail, and return a NULL pointer, if: the Network Configuration database does not exist; or, no entries exist in the Network Configuration database for the passed in netid string.

The freenetconfigent() subroutine will fail silently if: passed a NULL or invalid pointer; or, pass a pointer that was previously passed to freenetconfigent().

The nc_perror() subroutine will fail silently if: standard error is closed; or, msg is an invalid pointer.

The nc_sperror() subroutine will fail, and return a NULL pointer, if: no error exists.

The following errors can be returned:

[NC_NOERROR]: noerror
: The last network selection function called was successful or no network selection function has yet been called.
[NC_NOMEM]: outofmemory
: There was not sufficient memory for the last network selection function called to complete.
[NC_NOSET]: routinecalledbeforecallingsetnetpath()orsetnetconfig()
: The last call to endnetpath() or getnetpath(3) was called (incorrectly) before calling setnetpath(3).
[NC_OPENFAIL]: cannotopen/etc/netconfig
: The last call to a network selection function, setnetpath(3), could not open the /etc/netconfig file.
[NC_BADLINE]: errorin/etc/netconfig:field%dofline%d
: The last call to a network selection function detected a syntax error in the /etc/netconfig file at field %d of line %d.
[NC_NOTFOUND]: netidnotfoundin/etc/netconfig
: The netid argument to the last call to getnetconfigent(3) was not found in /etc/netconfig.
[NC_NOMOREENTRIES]: nomoreentriesin/etc/netconfig
: The last call to network selection function getnetpath(3) exhausted the entries in the /etc/netconfig file.
[???]: unknownerror
: An internal error occured in the libxnsl(3) library.

An error string associated with the error number can be obtained using nc_sperror() or printed to standard error with nc_perror().

FILES

/etc/netconfig: The Network Configuration database file. See netconfig(5).
/usr/lib/libxnsl.so: The X/Open Network Services Library shared object library.
/usr/lib/libxnsl.a: The X/Open Network Services Library static library.

BUGS

setnetconfig(), getnetconfig(), endnetconfig(), getnetconfigent(), freenetconfigent(), nc_perror() and nc_sperror(), have no known bugs.

COMPATIBILITY

These network configuration subroutines are compatible with SVR 4.2[2], and systems based on SVR 4.2[2], including AIX®[3], HP-UX®[4], Solaris®[5] and UnixWare®[6], with the following compatibility considerations:

---: Solaris®[5] and UnixWare®[6] describe the nc_sperror() subroutine as returning a pointer to thread-specific data and that the buffer could change at any point. While the error value is saved as thread-specific data, this implementation of nc_sperror() returns a pointer to a shared read-only string that is valid for the duration of the calling process.
---: OpenSS7 STREAMS Network Services Library stores the error condition in nc_error(3).
---: Diagnostic message strings are not documented and are incompatible.
---: Binary compatibility would only be coincidental.
---: On UNIX® systems, these utility subroutines are normally part of the Network Services Library, libnsl; however, Linux already has a library of that name (which unfortunately is missing these components), and, therefore, OpenSS7 STREAMS Network Services Library renames the library to libxnsl(3).

See libxnsl(3) for additional compatibility information.

CONFORMANCE

SVR 4.2[2].

HISTORY

The network selection subroutines first appeared in SVR 4.2[2]. These subroutines are related to the UNIX® STREAMS(9) implementation of network transport providers.

REFERENCES

[1]: RFC 1833, Binding Protocols for ONC RPC Version 2, August 1995, R. Srinivasan, The Internet Society. <http://www.ietf.org/rfc/rfc1833.txt>
[2]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[4]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>
[5]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[6]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>