netdir
Networking Services Library Functions netdir(3NSL)NAME
netdir, netdir_getbyname, netdir_getbyaddr, netdir_free, netdir_options, taddr2uaddr, uaddr2taddr, netdir_perror, netdir_sperror, netdir_mergeaddr - generic transport name- to-address translationSYNOPSIS
#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, const int struct_type); int netdir_options(const struct netconfig *config, const int option, const int fildes, char *point_to_args); char *taddr2uaddr(const struct netconfig *config, const struct netbuf *addr); struct netbuf *uaddr2taddr(const struct netconfig *config, const char *uaddr); 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 con- vert transport specific addresses into common structures and back again. The netconfig structure, described on the netconfig(4) manual page, identifies the transport. 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 structure contains the following members: char /* host name */ *h_serv; /* service name */ The nd_addrlist structure contains the following members: SunOS 5.8 Last change: 30 Dec 1996 1 Networking Services Library Functions netdir(3NSL) int n_cnt; /* number of addresses */ struct netbuf *n_addrs; netdir_getbyname() accepts some special-case host names. The host names are defined in <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(3C), which represents the address to which remote programs will bind their end- points. HOST_ANY Represents any host accessible by this transport pro- vider. HOST_ANY allows applications to specify a required service without specifying a particular host name. HOST_SELF_CONNECT Represents the host address that can be used to con- nect to the local host. 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 the address of a given host and service on all available transports, call the netdir_getbyname() routine with each struct netconfig structure returned by getnetconfig(3NSL). The netdir_getbyaddr() routine maps addresses to service names. This routine returns service, a list of host and ser- vice 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; /* number of hostservs found */ struct hostserv *h_hostservs; } The netdir_free() structure is used to free the structures allocated by the name to address translation routines. ptr points to the structure that has to be freed. The struct_type identifies the structure: SunOS 5.8 Last change: 30 Dec 1996 2 Networking Services Library Functions netdir(3NSL) struct netbuf ND_ADDR struct nd_addrlist ND_ADDRLIST struct hostserv ND_HOSTSERV struct nd_hostservlist ND_HOSTSERVLIST The universal address returned by taddr2uaddr() should be freed by free(). The netdir_options() routine is used to do all transport- specific setups and option management. fildes is the associ- ated file descriptor. option, fildes, and pointer_to_args are passed to the netdir_options() routine for the transport specified in config. Currently four values are defined for option: ND_SET_BROADCAST ND_SET_RESERVEDPORT ND_CHECK_RESERVEDPORT ND_MERGEADDR The taddr2uaddr() and uaddr2taddr() routines support trans- lation between universal addresses and TLI type netbufs. The taddr2uaddr() routine takes a struct netbuf data structure and returns a pointer to a string that contains the universal address. It returns NULL if the conversion is not possible. This is not a fatal condition as some tran- sports may not suppose a universal address form. uaddr2taddr() is the reverse of taddr2uaddr(). It returns the struct netbuf data structure for the given universal address. If a transport provider does not support an option, netdir_options returns -1 and the error message can be printed through netdir_perror() or netdir_sperror(). The specific actions of each option follow. ND_SET_BROADCAST Sets the transport provider up to allow broadcast, if the transport supports broadcast. fildes 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 fildes. ND_SET_RESERVEDPORT Allows the application to bind to a reserved port, if that concept exists for the transport provider. fildes SunOS 5.8 Last change: 30 Dec 1996 3 Networking Services Library Functions netdir(3NSL) is an unbound file descriptor into the transport. If pointer_to_args is NULL, fildes 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 any reserved port on the specified address. ND_CHECK_RESERVEDPORT Used to verify that the address corresponds to a reserved port, if that concept exists for the tran- sport provider. fildes is not used. pointer_to_args is a pointer to a netbuf structure that contains the 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. FILDES 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; /* the result */ If 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 transports, m_uaddr is exactly what s_uaddr is. RETURN VALUES The netdir_perror() routine prints an error message on the standard output stating why one of the name-to-address map- ping 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. netdir_sperror() returns a pointer to a buffer which con- tains the error message string. This buffer is overwritten on each call. In multithreaded applications, this buffer is implemented as thread-specific data.ATTRIBUTES
See attributes(5) for descriptions of the following attri- butes: SunOS 5.8 Last change: 30 Dec 1996 4 Networking Services Library Functions netdir(3NSL) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | MT-Level | MT-Safe | |_____________________________|_____________________________|SEE ALSO
gethostname(3C), getnetconfig(3NSL), getnetpath(3NSL), netconfig(4), attributes(5) SunOS 5.8 Last change: 30 Dec 1996 5