netdir(3N) netdir(3N)
NAME
netdir_getbyname, netdir_getbyaddr, netdir_free,
netdir_options, taddr2uaddr, uaddr2taddr, netdir_perror,
netdir_sperror - generic transport name-to-address translation
SYNOPSIS
cc [options] file -lnsl
#include <netdir.h>
int netdir_getbyname(const struct netconfig *config,
const struct nd_hostserv *service, struct nd_addrlist **addrs);
int netdir_getbyaddr(const struct netconfig *config,
struct nd_hostservlist **service, const struct netbuf *netaddr);
void netdir_free(void *ptr, int ident);
char *taddr2uaddr(const struct netconfig *config,
const struct netbuf *addr);
struct netbuf *uaddr2taddr(const struct netconfig *config,
const char *uaddr);
int netdir_options(const struct netconfig *netconfig, int option,
int fd, const char *pointer_to_args);
void netdir_perror(char *s);
char *netdir_sperror(void);
DESCRIPTION
These routines provide a generic interface for name-to-address
mapping that will work with all transport protocols. This
interface provides a generic way for programs to convert
transport-specific addresses into common structures and back
again.
The netdir_getbyname routine maps the machine name and service
name in the nd_hostserv structure to a collection of addresses
of the type understood by the transport identified in the
netconfig structure. This routine returns all addresses that
are valid for that transport in the nd_addrlist structure.
The netconfig structure is described on the netconfig(4)
manual page. The nd_hostserv and nd_addrlist structures have
the following elements.
nd_addrlist structure:
int n_cnt; /* number of netbufs */
struct netbuf *n_addrs; /* the netbufs */
nd_hostserv structure:
char *h_host; /* the host name */
char *h_serv; /* the service name */
Copyright 1994 Novell, Inc. Page 1
netdir(3N) netdir(3N)
netdir_getbyname accepts some special-case host names. These
host names are hints to the underlying mapping routines that
define the intent of the request. This information is
required for some transport provider developers to provide the
correct information back to the caller. The host names are
defined in netdir.h. The currently defined host names are:
HOST_SELF
Represents the address to which local programs can bind
their endpoints. HOST_SELF differs from the host name
provided by gethostname, which represents the address to
which remote programs can connect.
HOST_ANY
Represents any host accessible by this transport
provider. HOST_ANY allows applications to specify a
required service without specifying a particular host
name.
HOST_BROADCAST
Represents the address for all hosts accessible by this
transport provider. Network requests to this address
will be received by all machines.
All fields of the nd_hostserv structure must be initialized.
To find all available transports, call the netdir_getbyname
routine with each netconfig structure returned by the
getnetpath call.
To map NetWare service names to transport addresses, service
names are put in the host portion of the nd_hostserv
structure. The service portion is interpreted as follows: If
it contains a service type listed in /etc/saptypes, then the
socket portion of the returned transport address is the socket
number being advertised for that service. If it contains a
socket name listed in /etc/services, then the socket portion
of the returned transport address is socket number in
/etc/services. If it contains a decimal number, then the
socket portion of the transport address is the specified
socket number.
The netdir_getbyaddr routine maps addresses to service names.
This routine returns a list of host and service pairs that
would yield this address. If more than one tuple of host and
service name is returned then the first tuple contains the
Copyright 1994 Novell, Inc. Page 2
netdir(3N) netdir(3N)
preferred host and service names. The nd_hostservlist
structure contains the following members:
int h_cnt; /* the number of nd_hostservs */
struct hostserv *h_hostservs; /* the entries */
The netdir_free structure is used to free the structures
allocated by the name to address translation routines.
The following types of structures may be specified by the
ident argument:
ND_ADDR
Frees a netbuf structure.
ND_ADDRLIST
Frees the nd_addrlist structure, such as that allocated
by netdir_getbyname.
ND_HOSTSERV
Frees a nd_hostserv structure.
ND_HOSTSERVLIST
Frees the nd_hostservlist structure, such as that
allocated by netdir_getbyaddr.
NetWare transport addresses are mapped into lists of all
NetWare service names that match the network and node portions
of the specified transport address. The host portion of the
nd_hostserv structure contains the NetWare service name. The
socket portion of the transport address is interpreted as
follows: If the socket number is being advertised by a NetWare
service and the service type is in /etc/saptypes, then the
service type is returned in the service portion of the
nd_hostserv structure. If the socket number is in
/etc/services, then the name in /etc/services is returned in
the service portion of the nd_hostserv structure. The socket
number is converted into a decimal number and returned in the
service portion of the nd_hostserv structure.
The taddr2uaddr and uaddr2taddr routines support translation
between universal addresses and TLI/XTI type netbufs. They
take and return character string pointers. The taddr2uaddr
routine returns a pointer to a string that contains the
universal address and returns NULL if the conversion is not
possible. This is not a fatal condition, as some transports
may not support a universal address form.
Copyright 1994 Novell, Inc. Page 3
netdir(3N) netdir(3N)
The netdir_options routine is used to pass options in a
transport-independent manner to the transport provider
specified by netconfig.
If a transport provider does not support an option,
netdir_options returns -1 and sets _nderror to ND_FAILCTRL.
If an option is specified that is not on the above list,
netdir_options returns -1 and sets _nderror to ND_NOCTRL. In
case of any other failure, to perform the required action,
netdir_options returns -1 and sets _nderror to the appropriate
value.
The specific actions of each option follow.
ND_SET_BROADCAST
Sets the transport provider up to allow broadcast, if
the transport supports broadcast. fd is a file
descriptor into the transport (for example, the result
of a t_open of /dev/udp). pointer_to_args is not used.
If this completes, broadcast operations may be performed
on file descriptor fd.
ND_CLEAR_BROADCAST
Turns off permission to send broadcast messages for the
transport endpoint.
ND_SET_REUSEADDR
Allows the transport provider to bind additional
transport endpoints to the same local address to which
another endpoint has already been bound.
ND_CLEAR_REUSEADDR
Does not allow the transport provider to bind a
transport endpoint to a local address to which another
endpoint has already been bound.
ND_SET_RESERVEDPORT
Allows the application to bind to a reserved port, if
that concept exists for the transport provider. fd is a
file descriptor into the transport (it must not be bound
to an address). If pointer_to_args is NULL, fd will be
bound to a reserved port. If pointer_to_args is a
pointer to a netbuf structure, an attempt will be made
to bind to a reserved port on the specified address.
Copyright 1994 Novell, Inc. Page 4
netdir(3N) netdir(3N)
ND_CHECK_RESERVEDPORT
Used to verify that an address corresponds to a reserved
port, if that concept exists for the transport provider.
fd is not used. pointer_to_args is a pointer to a
netbuf structure that contains an address. This option
returns 0 only if the address specified in
pointer_to_args is reserved.
ND_MERGEADDR
Used to take a ``local address'' (such as the 0.0.0.0)
address and return a ``real address'' that client
machines can connect to. fd is not used.
pointer_to_args is a pointer to a struct nd_mergearg,
which has the following members:
char *s_uaddr; /* server's universal address */
char *c_uaddr; /* client's universal address */
char *m_uaddr; /* merged universal address */
For TCP/IP, for instance, s_uaddr could be 0.0.0.0.1.12
(for example, specifying a local port). The client
address, c_uaddr is ignored, and the merged address is
set to, for example, 192.11.109.89.1.2 upon the return
of the call.
The netdir_perror routine prints an error message on the
standard output stating why one of the name-to-address mapping
routines failed. The error message is preceded by the string
given as an argument.
The netdir_sperror routine returns a string containing an
error message stating why one of the name-to-address mapping
routines failed.
Return Values
netdir_getbyname and netdir_getbyaddr return 0 for success and
the value of nderror in case of failure.
taddr2uaddr and uaddr2taddr return NULL in case of failure.
netdir_options returns -1 in case of error and 0 for success.
All functions set _nderror in case of failure. For
netdir_options, when the fd parameter is used (denoting use of
TLI/XTI calls), t_errno may provide additional insights into
why a call failed.
Copyright 1994 Novell, Inc. Page 5
netdir(3N) netdir(3N)
Files
/usr/lib/locale/locale/LC_MESSAGES/uxnsl
REFERENCES
getnetpath(3N), get_nderror(3N)
NOTES
The return value and error reporting of netdir_options may be
inconsistent for some providers.
Copyright 1994 Novell, Inc. Page 6