netdir(3N) netdir(3N)
NAME
netdir: netdirgetbyname, netdirgetbyaddr, netdirfree, taddr2uaddr,
uaddr2taddr, netdirperror, netdiroptions, netdirsperror - generic
transport name-to-address translation
SYNOPSIS
#include <netdir.h>
int netdirgetbyname(struct netconfig *config,
struct ndhostserv *service,
struct ndaddrlist **addrs);
int netdirgetbyaddr(struct netconfig *config,
struct ndhostservlist **service,
struct netbuf *netaddr);
void netdirfree(void ptr, int ident);
char *taddr2uaddr(struct netconfig *config, struct netbuf *addr);
struct netbuf *uaddr2taddr(struct netconfig *config, char *uaddr);
int netdiroptions(struct netconfig *netconfig, int option, int fd,
char *pointtoargs);
void netdirperror(char *s);
char *netdirsperror(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 netdirgetbyname() routine maps the machine name and service name
in the ndhostserv 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 ndaddrlist structure. The ndhostserv and ndaddrlist struc-
tures have the following elements. The netconfig structure is
described in the netconfig(4) manual page.
struct ndaddrlist
int ncnt
struct netbuf *naddrs;
struct ndhostserv
char *hhost;
char *hserv;
Page 1 Reliant UNIX 5.44 Printed 11/98
netdir(3N) netdir(3N)
netdirgetbyname() 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 /usr/include/netdir.h. The
currently defined host names are:
HOSTSELF Represents the address to which local programs will
bind their endpoints. HOSTSELF differs from the host
name provided by gethostname(3N), which represents the
address to which remote programs will bind their end-
points.
HOSTANY Represents any host accessible by this transport pro-
vider. HOSTANY allows applications to specify a
required service without specifying a particular host
name.
HOSTBROADCAST 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 ndhostserv structure must be initialized.
To find all available transports, call the netdirgetbyname() routine
with each struct netconfig structure returned by the getnetpath(3N)
call.
The netdirgetbyaddr() 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 preferred host and service names.
struct ndhostservlist
int *hcnt;
struct hostserv *hhostservs;
The netdirfree() structure is used to free the structures allocated
by the name to address translation routines.
The taddr2uaddr() and uaddr2taddr() routines support translation
between universal addresses and TLI 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 suppose a universal address form.
option, fd, and pointertoargs are passed to the netdiroptions rou-
tine for the transport specified in netconfig. There are four values
for option:
Page 2 Reliant UNIX 5.44 Printed 11/98
netdir(3N) netdir(3N)
NDSETBROADCAST
NDSETRESERVEDPORT
NDCHECKRESERVEDPORT
NDMERGEADDR
If a transport provider does not support an option, netdiroptions
returns -1 and sets nderror to NDNOCTRL.
The specific actions of each option follow.
NDSETBROADCAST
Sets the transport provider up to allow broadcast, if the trans-
port supports broadcast. fd is a file descriptor into the trans-
port (i.e., the result of a topen of /dev/udp). pointertoargs
is not used. If this completes, broadcast operations may be per-
formed on file descriptor fd.
NDSETRESERVEDPORT
Allows the application to bind to a reserved port, if that con-
cept exists for the transport provider. fd is a file descriptor
into the transport (it must not be bound to an address). If
pointertoargs is NULL, fd will be bound to a reserved port. If
pointertoargs is a pointer to a netbuf structure, an attempt
will be made to bind to a reserved port on the specified address.
NDCHECKRESERVEDPORT
Used to verify that an address corresponds to a reserved port, if
that concept exists for the transport provider. fd is not used.
pointertoargs is a pointer to a netbuf structure that contains
an address. This option returns 0 only if the address specified
in pointertoargs is reserved.
NDMERGEADDR
Used to take a "local address" (like the 0.0.0.0 address that TCP
uses) and return a "real address" that client machines can con-
nect to. fd is not used. pointertoargs is a pointer to a struct
ndmergearg, which has the following form:
struct ndmergearg {
char *suaddr; /* server's universal address */
char *cuaddr; /* client's universal address */
char *muaddr; /* the result */
}
suaddr is something like 0.0.0.0.1.12, and, if the call is suc-
cessful, muaddr will be set to something like 192.11.109.89.1.12.
For most transports, muaddr is exactly what suaddr is.
Page 3 Reliant UNIX 5.44 Printed 11/98
netdir(3N) netdir(3N)
The netdirperror() 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 netdirsperror() routine returns a string containing an error mes-
sage stating why one of the name-to-address mapping routines failed.
SEE ALSO
gethostname(3N), getnetpath(3N), netconfig(4).
Page 4 Reliant UNIX 5.44 Printed 11/98