Manpage of NETPATH

NETPATH

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

NAME

netpath, setnetpath, getnetpath, endnetpath - Network Configuration path subroutines.

SYNOPSIS

#include <netconfig.h>

void *setnetpath(void);
struct netconfig *getnetpath(void *handle);
int endnetpath(void *handle);

ARGUMENTS

handle: an opaque pointer returned by setnetpath() to be used as an argument to calls to getnetpath().

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.

setnetpath(), getnetpath() and endnetpath() provide a mechanism to sequentialy access entries in the Network Configuration database that correspond to entries in the {NETPATH} environment variable. That is, the {NETPATH} environment variable acts as a filter specification that filters network identifiers.

setnetpath(): returns a pointer to an opaque datastructure used as a handle to the getnetpath() subroutine. setnetpath() is used to initialize client access to the database entries and set the access point to the first valid entry in the {NETPATH} environment variable. If the {NETPATH} environment variable is not set, all of the entries in the netconfig(5) database that are marked visible will be used instead.
getnetpath(),: when called successively with the handle returned by the call to setnetpath(), returns each valid Network Configuration database entry that appears in the {NETPATH} environment variable starting with the first. If the {NETPATH} environment variable is not set, all of the database entries that are marked visible will be used instead. Once the last entry is returned, getnetpath() will subsequently return NULL.
endnetpath(): releases client access to the database and frees for reuse any resources that were held by setnetpath() for use by getnetpath(). endnetpath() must only be called with a handle returned from a previous and corresponding call to setnetpath(). endnetpath() must be called for each call to setnetpath() with the corresponding handle pointer as the argument.

nc_perror(3) and nc_sperror(3) provide a mechanism for providing diagnostic messages upon failure. These subroutines are used for both netconfig(3) subroutines as well as the netpath subroutines described here.

NETPATH FORMAT

The format of the {NETPATH} environment variable is a sequence of zero or more network identification strings as described in netconfig(5), separated by colons. If the {NETPATH} environment variable is not set, these subroutines act as though the {NETPATH} environment variable consisted of each visible network identification string entry in the netconfig(5) database, in the order they occur in the database, separated by colons.

DATABASE FORMAT

The netconfig structure is defined in netconfig(3) and netconfig(5).

NOTICES

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

RETURN VALUE

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

Upon successful completion, getnetpath() return a pointer to a netconfig(3) structure. Otherwise, it returns NULL to indicate failure.

Upon successful completion, endnetpath() returns 0. Otherwise, -1 is returned and nc_error(3) is set to indicate the error.

ERROR HANDLING

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

ERRORS

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

The getnetpath() subroutine will fail, and return a NULL pointer, if: no etnries exist in the Network Configuration database corresponding to the {NETPATH} environment variable; or, the last entry in the Network Configuration database associated with the {NETPATH} environment variable has already been read with a previous call to getnetpath() and there are no more entries in the Network Configuration database corresponding to the {NETPATH} environment variable.

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

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.

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.

ENVIRONMENT

{NETPATH}: This environment variable contains the network path.

BUGS

setnetpath(), getnetpath() and endnetpath() had no known bugs.

COMPATIBILITY

These network configuraiton 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 configuration 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/>