Manpage of NETDIR

NETDIR

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

NAME

netdir, netdir_getbyaddr, netdir_getbyname, netdir_options, taddr2uaddr, uaddr2taddr, netdir_free, netdir_perror, netdir_sperror - Network Directory service subroutines.

SYNOPSIS

#include <netconfig.h>

int netdir_getbyname(struct netconfig *config, struct nd_hostserv *service, struct nd_addrlist **addrs);
int netdir_getbyaddr(struct netconfig *config, struct nd_hostservlist **services, struct netbuf *addr);
int netdir_options(struct netconfig *config, int option, int fd, char *point_to_args);
char *taddr2uaddr(struct netconfig *config, struct netbuf *addr);
struct netbuf *uaddr2taddr(struct netconfig *config, struct netbuf *addr);
void netdir_free(void *ptr, int struct_type);
void netdir_perror(char *msg);
char *netdir_sperror(void);

ARGUMENTS

config

A pointer to a netconfig structure describing the network transport provider returned by getnetconfig(3) or getnetpath(3).

service

A pointer to a nd_hostserv structure describing the name of a host service.

services

A pointer to a nd_hostservlist array describing the name(s) of a host service.

addr

A pointer to a netbuf structure containing a transport or universal address.

option

The name of a universal network option. It can have values

The following are Solaris®[1] TI-RPC 2.3 options:

ND_SET_BROADCAST: Permit use of broadcast address on transport endpoint.
ND_SET_RESERVEDPORT: Bind to a reserved port on transport endpoint.
ND_CHECK_RESERVEDPORT: Check if port in address is reserved.
ND_MERGEADDR: Merge underspecified server address with client address.
ND_JOIN_MULTICAST: Join a multicast group.
ND_LEAVE_MULTICAST: Leave a multicast group.

The following are UnixWare®[2] extensions:

ND_CLEAR_BROADCAST: Prohibit use of broadcast address on transport endpoint.
ND_SET_REUSEADDR: Permit reuse of local addresses for transport endpoint.
ND_CLEAR_REUSEADDR: Prohibit reuse of local addresses for transport endpoint.

The following are OpenSS7tm extensions:

ND_SET_DONTROUTE: Do not route packets from transport endpoint.
ND_CLEAR_DONTROUTE: Route packets from transport endpoint.
ND_SET_KEEPALIVE: Set keepalive on transport endpoint.
ND_CLEAR_KEEPALIVE: Clear keepalive on transport endpoint.
ND_SET_PRIORITY: Set priority of transport endpoint.

fd

A file descriptor associated with a transport endpoint of the type associated with the config netconfig structure.

point_to_args

A pointer to the argument values associated with option.

ptr

A pointer to a structure to free.

struct_type

The structure type to free. This argument can have values:

ND_ADDR: struct netbuf
ND_ADDRLIST: struct nd_addrlist
ND_HOSTSERV: struct nd_hostserv
ND_HOSTSERVLIST: struct nd_hostservlist

msg

A pointer to a string to prefix to the printed error message (followed by a colon).

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.

DATABASE FORMAT

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

STRUCTURE FORMAT

The netbuf structure is defined in <xti.h> and is structured as follows:

struct netbuf {
    unsigned int maxlen;
    unsigned int len;
    char *buf;
};

maxlen: the maximum length of the supplied buffer, buf.
len: the length of the filled buffer, buf.
buf: a pointer to the buffer.

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

struct nd_addrlist {
    int n_cnt;               /* number of addresses */
    struct netbuf *n_addrs;  /* the addresses (array) */
};

n_cnt: the number of addresses in the list.
n_addrs: a pointer to an array of netbuf structures forming the address list.

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

struct nd_hostserv {
    char *h_name;  /* host name */
    char *h_serv;  /* service name */
};

h_name

the host (machine) name.

The following special host names are defined in <netdir.h>:

HOST_SELF: Local host name.
HOST_ANY: Any host name.
HOST_BROADCAST: All addresses accessible by transport.
HOST_SELF_CONNECT: Address for connecting to the local host.
HOST_SELF_BIND: Bind to one's self.
HOST_ALLNODES: All nodes (broadcast or rpcbind broadcast).
HOST_RPCNODES: All RPC nodes (multicast or rpcbind multicast).

h_serv

the service name.

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

struct nd_hostservlist {
    int *h_cnt;  /* number of hostservs found */
    struct hostserv *h_hostservs;
};

h_cnt: the number of services in the list.
h_hostservs: a pointer to an array of nd_hostserv structures forming the service list.

NOTICES

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

RETURN VALUE

Upon successful completion, netdir_getbyname(), netdir_getbyaddr() and netdir_options() return 0. Otherwise, -1 is returned and _nderror is set to indicate the error.

ERRORS

A name-to-address mapping function will fail if:

[ND_TRY_AGAIN]: n2a:non-authoritativehostnotfound
The host was not found, however, a name-to-address mapping function suffered a temporary failure (such as a timeout).
[ND_NO_RECOVERY]: n2a:non-recoverableerror
The last name-to-address translation function suffered an unrecoverable error in one of its lookup libraries.
[ND_NO_DATA]: n2a:nodatarecordofrequestedtype
The last name-to-address translation function could find no data of the requested type in one of its lookup libraries.
[ND_NO_ADDRESS]: n2a:nodatarecordofrequestedtype
The last name-to-address translation function could find no address of the requested type in one of its lookup libraries.
[ND_BADARG]: n2a:badargumentspassedtoroutine
The last name-to-address translation function was passed a bad argument.
[ND_NOMEM]: n2a:memoryallocationfailed
The last name-to-address translation function could not allocate memory necessary to complete the operation.
[ND_OK]: n2a:successfulcompletion
The last name-to-address translation function completed successfully, or there was no previous name-to-address translation function called.
[ND_NOHOST]: n2a:hostnamenotfound
The last name-to-address translation function, netdir_getbyname(3), could not find, or does not support, the specified host name.
[ND_NOSERV]: n2a:servicenamenotfound
The last name-to-address translation function, netdir_getbyname(3), could not find, or does not support, the specified service name.
[ND_NOSYM]: n2a:symbolmissinginsharedobject:%s
One of the required symbols, see netdir(5), was missing from a shared object specified in the nc_lookup member of the netconfig(5) structure referenced by a config argument. %s is replaced with the last dlerror(3) string.
[ND_OPEN]: n2a:couldnotopensharedobject:%s
One of the shared objects specified in the nc_lookup member of the netconfig(5) structure referenced by a config argument could not be opened. %s is replaced with the last dlerror(3) string.
[ND_ACCESS]: n2a:accessdeniedforsharedobject
One of the shared objects specified in the nc_lookup member of the netconfig(5) structure referenced by a config argument could not be opened due to access permission.
[ND_UKNWN]: n2a:attempttofreeunknownobject
netdir_free(3) was called with an unknown struct_type argument value.
[ND_NOCTRL]: n2a:unknownoptionpassed
netdir_options(3) was passed an unknown option argument value.
[ND_FAILCTRL]: n2a:controloperationfailed
The netdir_options(3) control operation failed.
[ND_SYSTEM]: n2a:systemerror
During the last name-to-address translation function, a system error occurred. The Linux system error is in errno(3). The xti(3) error in t_errno(3) might also provide some insight into the error.
[ND_NOCONVERT]: n2a:conversionnotpossible
During the last name-to-address translation function it was discovered that character string conversion was not possible.
[other]: n2a:unknownerror%d
An internal error occured in the libxnsl(3) library or a loaded shared object. %d is the decimal number of the error number that was contained in _nderror.

An error message corresponding to the _nderror value can be retrieved using netdir_sperror() or printed to standard error using netdir_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

netdir_getbyaddr(), netdir_getbyname(), netdir_options(), taddr2uaddr(), uaddr2taddr(), netdir_free(), netdir_perror() and netdir_sperror() have no known bugs.

COMPATIBILITY

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

---: Solaris®[1] and UnixWare®[2] 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.
---: Solaris®[1] does not document the ND_CLEAR_BROADCAST, ND_SET_REUSEADDR nor ND_CLEAR_REUSEADDR options to netdir_options(). UnixWare®[2] does.
---: UnixWare® documents[2] that _nderror contains the cause of failure and that t_errno(3) may provide some additional insights into why a call failed.
: OpenSS7 STREAMS Network Services Library stores the error condition in _nderror.
---: 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[4].

HISTORY

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

REFERENCES

[1]: Solaris® 8, Solaris 8 Docmentation, 2001, (Santa Clara, California), Sun Microsystems, Inc., Sun. <http://docs.sun.com/>
[2]: UnixWare® 7.1.3, UnixWare 7.1.3 (OpenUnix 8) Documentation, 2002, (Lindon, Utah), Caldera International, Inc., Caldera. <http://uw713doc.sco.com/>
[3]: RFC 1833, Binding Protocols for ONC RPC Version 2, August 1995, R. Srinivasan, The Internet Society. <http://www.ietf.org/rfc/rfc1833.txt>
[4]: 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.
[5]: AIX® 5L Version 5.1, AIX 5L Version 5.1 Documentation, 2001, (Boulder, Colorado), Internatonal Business Machines Corp., IBM. <http://publibn.boulder.ibm.com/>
[6]: HP-UX® 11i v2, HP-UX 11i v2 Documentation, 2001, (Palo Alto, California), Hewlett-Packard Company, HP. <http://docs.hp.com/>