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


NETCONFIG

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

SEE ALSO

netconfig(5), netpath(3), netdir(3), netdir_getbyname(3), RFC 1833[1].

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.
---
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 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/>

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 22:58:41 GMT.

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



Index

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

This document was created by man2html, using the manual pages.
Time: 22:58:41 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.