'\"macro stdmacro
.if n .pH g3n.netdir @(#)netdir	40.9 of 12/26/89
.\" Copyright 1989 AT&T
.\" @(#)netdir.3n 1.8 89/05/01 SMI;
.\" Copyright (c) 1988 Sun Microsystem's, Inc. - All Rights Reserved.
.nr X
.if \nX=0 .ds x} netdir 3N "" "\&"
.if \nX=1 .ds x} netdir 3N ""
.if \nX=2 .ds x} netdir 3N "" "\&"
.if \nX=3 .ds x} netdir "" "" "\&"
.TH \*(x}
.SH NAME
\f4netdir_getbyname\fP, \f4netdir_getbyaddr\fP, \f4netdir_free\fP, \f4netdir_mergeaddr\fP, \f4taddr2uaddr\fP, \f4uaddr2taddr\fP, \f4netdir_perror\fP, \f4netdir_sperror\fP \- generic transport name-to-address translation
.SH SYNOPSIS
.nf
.ft CW
#include <netdir.h>
.sp .5
int
netdir_getbyname(config, service, addrs)
	struct netconfig  *config;
	struct nd_hostserv  *service;
	struct nd_addrlist  **addrs;
.sp .5
int
netdir_getbyaddr(config, service, netaddr)
	struct netconfig  *config;
	struct nd_hostservlist  **service;
	struct netbuf  *netaddr;
.sp .5
void
netdir_free(ptr, ident)
	void *ptr;
	int ident;
.sp .5
int
netdir_mergeaddr(config, mrg_uaddr, s_uaddr, c_uaddr)
	struct netconfig  *config;
	char  **mrg_uaddr, *s_uaddr, *c_uaddr;
.sp .5
char *
taddr2uaddr(config, addr)
	struct netconfig  *config;
	struct netbuf  *addr;
.sp .5
struct netbuf *
uaddr2taddr(config, uaddr)
	struct netconfig  *config;
	char  *uaddr;
.sp .5
int
netdir_options(netconfig, option, fd, pointer_to_args)
	struct netconfig  *netconfig;
	int  option;
	int fd;
	char  *point_to_args;
.sp .5
void
netdir_perror(s)
char  *s;
.sp .5
char *
netdir_sperror()
.fi
.ft R
.P
.\"[\(rh  Mike: syntax for netdir_ops? \(lh]
.SH DESCRIPTION
.LP
These routines provide a generic interface
for name-to-address 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.
.LP
The 
\f4netdir_getbyname(\|)\f1
routine maps the machine name and service name in the \f4nd_hostserv\fP
structure to
a collection of addresses of the type understood by the transport
identified in the \f4netconfig\fP structure.
This routine returns all addresses that are valid
for that transport in the \f4nd_addrlist\fP structure.
The \f4nd_hostserv\fP and \f4nd_addrlist\fP structures have the
following elements.
The \f4netconfig\fP structure is described on the \f4netconfig\fP(4)
manual page.
.sp .5
.RS
.ft CW
.nf
struct nd_addrlist
	int n_cnt
	struct netbuf  *n_addrs;
.sp .5
struct nd_hostserv
	char  *h_host;
	char  *h_serv;
.fi
.ft R
.RE
.sp .5
.br
.ne 8
.LP
\f4netdir_getbyname(\|)\f1
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 
\f4/usr/include/netdir.h\f1.
The currently defined host names are:
.sp .5
.TP 12
\f4HOST_SELF\fP
Represents the address to which local
programs will bind their endpoints.
\f4HOST_SELF\fP differs from the host name provided by
\f4gethostname\f1(3),
which represents the address to which
.I remote
programs will bind their endpoints.
.TP
\f4HOST_ANY\fP
Represents any host accessible by this transport
provider. 
\f4HOST_ANY\fP allows applications to specify a required service
without specifying a particular host name. 
.TP
\f4HOST_BROADCAST\fP
Represents the address for all hosts 
accessible by this transport provider.
Network requests to this address will be received by all machines.
.LP
All fields of the \f4nd_hostserv\fP structure must be initialized.
.LP
To find all available transports,
call the 
\f4netdir_getbyname(\|)\f1
routine with each
\f4struct netconfig\f1
structure returned by the
\f4getnetpath\f1(3N)
call.
.LP
The
\f4netdir_getbyaddr(\|)\f1
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.
.RS
.ft CW
.sp .5
.nf
struct nd_hostservlist
	int  *h_cnt;
	struct hostserv  *h_hostservs;
.fi
.ft R
.RE
.LP
The 
\f4netdir_free(\|)\f1
structure is used to free the 
structures allocated by the name to address translation
routines.
.LP
The
\f4netdir_mergeaddr(\|)\f1
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 
.I s_uaddr
parameter,
and the address of the endpoint that a request came in on, which is pointed
to by the 
.I c_uaddr
paramter,
to create an optimized address for communication with
the service.
The service address should be an address returned by the 
\f4netdir_getbyname(\|)\f1
call, specified with the special host name 
\f4\s-1HOST_SELF\s0\f1.
.LP
The
\f4taddr2uaddr(\|)\f1
and
\f4uaddr2taddr(\|)\f1
routines support translation between universal addresses and
.SM TLI
type netbufs.
The take and return character string pointers.
The
\f4taddr2uaddr(\|)\f1
routine returns a pointer to a string
that contains the universal
address and returns
.SM NULL
if the conversion is not possible.
This is not a fatal condition as some
transports may not suppose
a universal address form.
.P
\f2option\fP, \f2fd\fP, and \f2pointer_to_args\fP are passed to
the \f4netdir_options\fP routine for the transport specified
in \f4netconfigp\fP.
.\"[\(rh  Correct? \(lh]
There are four values for \f2option\fP:
.sp .5
.nf
.in +.5i
\f4ND_SET_BROADCAST
ND_SET_RESERVEDPORT
ND_CHECK_RESERVEDPORT
ND_MERGEADDR\fP
.in -.5i
.sp .5
.fi
If a transport provider does not support an option, \f4netdir_options\fP
returns \f4-1\fP and sets \f4_nderror\fP to \f4ND_NOCTRL\fP.
.P
The specific actions of each option follow.
.TP 20
\f4ND_SET_BROADCAST\fP
Sets the transport provider up to allow broadcast, if
the transport supports broadcast.
\f2fd\fP is a file descriptor into the transport (i.e.,
the result of a \f4t_open\fP of \f4/dev/udp\fP).
\f2pointer_to_args\fP
is not used.
If this completes, broadcast operations may be performed
on file descriptor \f2fd\fP.
.TP
\f4ND_SET_RESERVEDPORT\fP
Allows the application to bind to a reserved port, if that concept
exists for the transport provider.
\f2fd\fP is a file descriptor into the transport (it must
not be bound to an address).
If \f2pointer_to_args\fP is \f4NULL\fP,
\f2fd\fP will be bound to a reserved port.
If \f2pointer_to_args\fP
is a pointer to a \f4netbuf\fP structure,
an attempt will be made to bind to a reserved
port on the specified address.
.TP
\f4ND_CHECK_RESERVEDPORT\fP
Used to verify that an address corresponds to
a reserved port, if that concept exists for the transport
provider.
\f2fd\fP is not used.
\f2pointer_to_args\fP is a pointer to a \f4netbuf\fP structure
that contains an
address.
This option returns \f40\fP only if the address specified
in \f2pointer_to_args\fP is reserved.
.TP
\f4ND_MERGEADDR\fP
Used to take a ``local address'' (like the \f40.0.0.0\fP
address that TCP uses) and return a ``real address'' that
client machines can connect to.
\f2fd\fP is not used.
\f2pointer_to_args\fP is a pointer to a \f4struct nd_mergearg\fP, which
has the following form:
.sp .5
.nf
\s-1\f4struct nd_mergearg {
	char *s_uaddr;  /* server's universal address */
	char *c_uaddr;  /* client's universal address */
	char *m_uaddr;  /* the result */
}\fP\s+1
.fi
.sp .5
\f4s_uaddr\fP is something like \f40.0.0.0.1.12\fP, and, if the call
is successful, \f4m_uaddr\fP will be set to something like
\f4192.11.109.89.1.12\fP.
For most transports, \f4m_uaddr\fP is
exactly what \f4s_uaddr\fP is.
.LP
The
\f4netdir_perror()\f1
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.
.LP
The
\f4netdir_sperror()\f1
routine returns a string containing an error message stating why
one of the name-to-address mapping routines failed.
.SH SEE ALSO
\f4getnetpath\f1(3N)
