NAME

netdir_getbyname, netdir_getbyaddr, netdir_free, netdir_mergeaddr, taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror - generic transport name-to-address translation

SYNOPSIS

#include <netdir.h>

int
netdir_getbyname(config, service, addrs)
     struct netconfig  *config;
     struct nd_hostserv  *service;
     struct nd_addrlist  **addrs;
int
netdir_getbyaddr(config, service, netaddr)
     struct netconfig  *config;
     struct nd_hostservlist  **service;
     struct netbuf  *netaddr;

void
netdir_free(ptr, ident)
     void *ptr;
     int ident;
int
netdir_mergeaddr(config, mrg_uaddr, s_uaddr, c_uaddr)
     struct netconfig  *config;
     char  **mrg_uaddr, *s_uaddr, *c_uaddr;

char *
taddr2uaddr(config, addr)
     struct netconfig  *config;
     struct netbuf  *addr;
struct netbuf *
uaddr2taddr(config, uaddr)
     struct netconfig  *config;
     char  *uaddr;

int
netdir_options(netconfig, option, fd, pointer_to_args)
     struct netconfig  *netconfig;
     int  option;
     int fd;
     char  *point_to_args;
void
netdir_perror(s)
char  *s;

char *
netdir_sperror()

DESCRIPTION

These routines provide a generic interface for name-toaddress mapping that will work with a 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 nd_hostserv and nd_addrlist structures have the following elements. The netconfig structure is described on the netconfig(4) manual page.

struct nd_addrlist
     int n_cnt
     struct netbuf  *n_addrs;
struct nd_hostserv
     char  *h_host;
     char  *h_serv;

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 /usr/include/netdir.h. The currently defined host names are:

HOST_SELF Represents the address to which local programs will bind their endpoints. HOST_SELF differs from the host name provided by gethostname(3), which represents the address to which remote programs will bind their endpoints.

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 struct netconfig structure returned by the getnetpath(3N) call.

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 preferred host and service names.

struct nd_hostservlist
     int  *h_cnt;
     struct hostserv  *h_hostservs;

The netdir_free() structure is used to free the structures allocated by the name to address translation routines.

The netdir_mergeaddr() routine is used by a network service to return an optimized network addresses to a client. This routine takes the universal address of the endpoint that the service has bound to, which is pointed to by the s_uaddr parameter, and the address of the endpoint that a request came in on, which is pointed to by the c_uaddr paramter, to create an optimized address for communication with the service. The service address should be an address returned by the netdir_getbyname() call, specified with the special host name HOST_SELF.

The taddr2uaddr() and uaddr2taddr() routines support  trans-
lation  between  universal  addresses  and TLI type netbufs.
The  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   pointer_to_args   are  passed  to  the
netdir_options  routine  for  the  transport  specified   in
netconfigp.  There are four values for option:
     ND_SET_BROADCAST
     ND_SET_RESERVEDPORT
     ND_CHECK_RESERVEDPORT
     ND_MERGEADDR

If a transport provider does not support an option, netdir_options returns -1 and sets _nderror to ND_NOCTRL. 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 (i.e., 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_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.

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'' (like the 0.0.0.0 address that TCP uses) 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 form:

struct nd_mergearg {
     char *s_uaddr;  /* server's universal address */
     char *c_uaddr;  /* client's universal address */
     char *m_uaddr;  /* the result */
}
s_uaddr is something like  0.0.0.0.1.12,
and,  if the call is successful, m_uaddr
will   be   set   to   something    like
192.11.109.89.1.12.    For   most  tran-
sports, m_uaddr is exactly what  s_uaddr
is.

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.

SEE ALSO

getnetpath(3N)