OpenSS7
SS7 for the
Common Man
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.
Last modified: Mon, 28 Apr 2008 18:38:30 GMT
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Quick Links

Download

SCTP

SIGTRAN

SS7

Hardware

STREAMS

Asterisk

Related

Package

Manual

FAQ

Man Pages

Applications

SS7 Stack

ISDN Stack

SIGTRAN Stack

VoIP Stack

MG Stack

SS7/ISDN Devices

IP Transport

Embedded Systems

OS

Documentation

FAQ

SIGTRAN

Design

Conformance

Performance

References

Man Pages

Manuals

Papers

Home

Overview

Status

Documentation

Resources

About

News

Description: Manual Page

Keywords: ss7 ss7/ip ss7 over ip ss7 mtp ss7 sccp ss7 tcap sigtran mtp sccp tcap openss7 acb56 linux telephony pstn linux telephony linux nebs linux compactpci


NETPATH

Section: The OpenSS7 Project Library Calls (3)
Updated: Sun, 25 Jun 2017 05:25:15 GMT
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.

SEE ALSO

environ(5), netconfig(5), netconfig(3), nc_perror(3), nc_sperror(3), netdir(3), RFC 1833[1].

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.
---
The OpenSS7 Project 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, The OpenSS7 Project 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/>

TRADEMARKS

OpenSS7tm
is a trademark of OpenSS7 Corporation.
Linux®
is a registered trademark of Linus Torvalds.
UNIX®
is a registered trademark of The Open Group.
Solaris®
is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

The OpenSS7 Project: Package OpenSS7 version 0.9.2 released Sun, 25 Jun 2017 05:25:15 GMT.

Copyright©1997-2008OpenSS7 Corp.
All Rights Reserved.
(See roff source for permission notice.)



Index

NAME
SYNOPSIS
ARGUMENTS
DESCRIPTION
NETPATH FORMAT
DATABASE FORMAT
NOTICES
RETURN VALUE
ERROR HANDLING
ERRORS
FILES
ENVIRONMENT
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 05:25:15 GMT, June 25, 2017
OpenSS7
SS7 for the
Common Man
Home TopIndex FirstPrev Next LastMore Download Info FAQ Mail  Home -> Documentation -> Man Pages -> Manual Page
Last modified: Mon, 28 Apr 2008 18:38:30 GMT
© Copyright 1997-2007 OpenSS7 Corporation All Rights Reserved.