sl@0: /** @file  ../include/netdb.h
sl@0: @internalComponent
sl@0: */
sl@0: 
sl@0: /** @fn  endservent(void)
sl@0: 
sl@0: Refer to  getservent() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  gethostbyaddr(const char *addr, int length, int format)
sl@0: @param addr
sl@0: @param length
sl@0: @param format
sl@0: Refer to  gethostbyname() for the documentation
sl@0: @see getaddrinfo()
sl@0: @see getnameinfo()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  gethostbyname(const char *name)
sl@0: @param name
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  gethostbyaddr() 
sl@0: 
sl@0: @return   The gethostbyname and gethostbyaddr functions return NULL if an error occurs or a valid hostent 
sl@0: structure otherwise.
sl@0: 
sl@0: The gethostbyname, and gethostbyaddr functions each return a pointer to an object with the following structure describing an internet host referenced by name or by address, respectively. 
sl@0: 
sl@0: The name argument passed to gethostbyname should point to a NUL -terminated hostname. The addr argument passed to gethostbyaddr should point to an address which is len bytes long, in binary form (i.e., not an IP address in human readable ASCII form). The type argument specifies the address family (e.g. AF_INET, etc.) of this address. 
sl@0: 
sl@0: The structure returned contains either the information obtained from the name server, 
sl@0: 
sl@0: @code
sl@0: struct  hostent {
sl@0:         char    *h_name;        // official name of host
sl@0:         char    **h_aliases;    // alias list 
sl@0:         int     h_addrtype;     // host address type 
sl@0:         int     h_length;       // length of address 
sl@0:         char    **h_addr_list;  // list of addresses from name server 
sl@0: };
sl@0: #define h_addr  h_addr_list[0]  //address, for backward compatibility
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: 
sl@0: The members of this structure are: 
sl@0: @code
sl@0: h_name  Official name of the host.  
sl@0: h_aliases  A NULL -terminated array of alternate names for the host.  
sl@0: h_addrtype  The type of address being returned; usually AF_INET.  
sl@0: h_length  The length, in bytes, of the address.  
sl@0: h_addr_list  A NULL -terminated array of network addresses for the host. Host addresses are returned in network byte order.  
sl@0: h_addr  The first address in h_addr_list; this is for backward compatibility.  
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: When using the nameserver, gethostbyname will search for the named host in the current domain and its parents unless the name ends in a dot. 
sl@0: 
sl@0: getaddrinfo and getnameinfo functions are preferred over the gethostbyname, and gethostbyaddr functions. 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<arpa/inet.h>
sl@0: #include <sys/socket.h>
sl@0: #include <netinet/in.h>
sl@0: #include <netdb.h>
sl@0: #include <string.h>
sl@0: Int main()
sl@0: {
sl@0: struct hostent *hp = 0;
sl@0: char *test_url=www.google.com:
sl@0: hp = gethostbyname(test_url);
sl@0: if(hp==NULL)
sl@0: printf("gethostbyname failed"):
sl@0: else
sl@0: printf("gethostbyname passed");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Gethostbyname passed
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<arpa/inet.h>
sl@0: #include <sys/socket.h>
sl@0: #include <netinet/in.h>
sl@0: #include <netdb.h>
sl@0: #include <string.h>
sl@0: #define urlsize 50
sl@0: Int main()
sl@0: {
sl@0: struct hostent *hp = 0;
sl@0: char addr[256];
sl@0: unsigned long  test_addr;
sl@0: strcpy(addr," 147.243.3.83");
sl@0: test_addr=inet_addr(addr);
sl@0: struct hostent *hp;
sl@0: hp=gethostbyaddr((const char *)&test;_addr,sizeof(test_addr),AF_INET);
sl@0: if(hp)
sl@0: printf("DNS query resolved");
sl@0: else
sl@0: printf("gethostbyaddr failed");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Diagnostics:
sl@0: 
sl@0:  Error return status from gethostbyname and gethostbyaddr is indicated by return of a NULL pointer.
sl@0: The external integer h_errno may then be checked to see whether this is a temporary failure
sl@0: or an invalid or unknown host.
sl@0: The routine
sl@0: If its argument string is non- NULL, it is printed, followed by a colon and a space.
sl@0: The error message is printed with a trailing newline. The variable h_errno can have the following values: TRY_AGAIN This is usually a temporary error
sl@0: and means that the local server did not receive
sl@0: a response from an authoritative server.
sl@0: A retry at some later time may succeed. NO_RECOVERY Some unexpected server failure was encountered.
sl@0: This is a non-recoverable error.
sl@0: 
sl@0: @see getaddrinfo()
sl@0: @see getnameinfo()
sl@0: 
sl@0: 
sl@0: Bugs:
sl@0: 
sl@0:  These functions use a thread-specific data storage; if the data is needed 
sl@0: for future use it should be copied before any subsequent calls overwrite it. Though these functions are thread-safe the getaddrinfo family of functions is recommended 
sl@0:   instead. Only the Internet
sl@0: address format is currently understood. 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getprotobyname(const char *name)
sl@0: @param name
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  getprotobynumber() 
sl@0: 
sl@0: @return   Null pointer
sl@0: (0) returned on
sl@0: error.
sl@0: 
sl@0: The getprotobyname, and getprotobynumber functions each return a pointer to an object with the following structure from the network protocol data base 
sl@0: @code
sl@0: struct  protoent {
sl@0:         char    *p_name;        /* official name of protocol */
sl@0:         char    **p_aliases;    /* alias list */
sl@0:         int     p_proto;        /* protocol number */
sl@0: };
sl@0: @endcode
sl@0: 
sl@0: The members of this structure are: 
sl@0: @code
sl@0: p_name  The official name of the protocol.  
sl@0: p_aliases    A zero terminated list of alternate names for the protocol.  
sl@0: p_proto  The protocol number.  
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: The getprotobyname function and getprotobynumber sequentially search from the beginning of the database until a matching protocol name or protocol number is found, 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<stdio.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: Int main()
sl@0: {
sl@0: struct protoent *p =0;
sl@0: char *protoname="tcp";
sl@0: p=getprotobyname(protoname);
sl@0: if(p!=NULL)
sl@0: printf("protocol not supported:");
sl@0: else
sl@0: printf("protocol supported");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Protocol supported/not supported based on the support for protocol
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<stdio.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: int main()
sl@0: 	{
sl@0: 	struct protoent *p =0;
sl@0: 	int protonum=6;
sl@0: 	p=getprotobynumber(protonum);
sl@0: 	if(p!=NULL)
sl@0: 		printf("protocol not supported:");
sl@0: 	else
sl@0: 		printf("protocol supported");
sl@0: 	return 0;
sl@0: 	}
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Protocol supported/not supported based on the support for protocol
sl@0: 
sl@0: @endcode
sl@0:  The getprotobynumber, getprotobyname, functions appeared in BSD 4.2 .
sl@0: 
sl@0: Bugs:
sl@0: 
sl@0:  These functions use a thread-specific data space; if the data is needed for 
sl@0: future use it must be copied before any subsequent calls overwrite it. Only the 
sl@0: Internet protocols are currently understood. 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getprotobynumber(int proto)
sl@0: @param proto
sl@0: 
sl@0: Refer to  getprotobyname() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getservbyname(const char *name, const char *proto)
sl@0: @param name
sl@0: @param proto
sl@0: Refer to  getservent() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getservbyport(int port, const char *proto)
sl@0: @param port
sl@0: @param proto
sl@0: Refer to  getservent() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getservent(void)
sl@0: 
sl@0: Note: This description also covers the following functions -
sl@0:  getservbyname()  getservbyport()  setservent()  endservent() 
sl@0: 
sl@0: @return   getservent, getservbyname and getservbyport functions return the servent structure, or a NULL pointer if an error occurs or the end of the file is reached.
sl@0: 
sl@0: @code
sl@0:  s_name The official name of the service.
sl@0:  s_aliases
sl@0:   A zero terminated list of alternate names for the service.
sl@0:  s_port The port number at which the service resides.
sl@0:  Port numbers are returned in network byte order.
sl@0:  s_proto The name of the protocol to use when contacting the
sl@0:  service.
sl@0: 
sl@0: @endcode
sl@0:   
sl@0: @code
sl@0: The getservent, getservbyname, and getservbyport functions
sl@0: each return a pointer to an object with the
sl@0: following structure
sl@0: containing the broken-out
sl@0: fields of a line in the network services data base, c:/sys/data/services. 
sl@0: structservent {
sl@0: char*s_name;/* official name of service */
sl@0: char**s_aliases;/* alias list */
sl@0: ints_port;/* port service resides at */
sl@0: char*s_proto;/* protocol to use */
sl@0: };
sl@0: @endcode
sl@0: 
sl@0:  The members of this structure are: s_name The official name of the service. s_aliases  A zero terminated list of alternate names for the service. s_port The port number at which the service resides.
sl@0: Port numbers are returned in network byte order. s_proto The name of the protocol to use when contacting the
sl@0: service.
sl@0: 
sl@0:  The getservent function
sl@0: reads the next line of the file, opening the file if necessary.
sl@0: 
sl@0:  The setservent function
sl@0: opens and rewinds the file.
sl@0: 
sl@0:  The endservent function
sl@0: closes the file.
sl@0: 
sl@0:  The getservbyname and getservbyport functions
sl@0: sequentially search from the beginning
sl@0: of the file until a matching
sl@0: protocol name or
sl@0: port number (which must be specified in
sl@0: network byte order) is found,
sl@0: or until EOF is encountered.
sl@0: If a protocol name is also supplied (non- NULL ), searches must also match the protocol.
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: int main()
sl@0: {
sl@0: Char *service="http";
sl@0: Char *protocol="tcp";
sl@0: Struct servent *p=0;
sl@0: P=getservbyname(service,protocol);
sl@0: if(p!=NULL)
sl@0: printf("service not supported:");
sl@0: else
sl@0: printf("Service  supported");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: int main()
sl@0: {
sl@0: struct servent *p;
sl@0: char *protocol="tcp";
sl@0: int port;
sl@0: port=htons(80);
sl@0: p=(port,protocol);
sl@0: if(p)
sl@0: {
sl@0: Printf("port is  assigned");
sl@0: else
sl@0: printf("port is not assigned");
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Port is assigned
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: Int main()
sl@0: {
sl@0: struct servent *p;
sl@0: p=getservent();
sl@0: if(p)
sl@0: printf("getservent successful");
sl@0: else
sl@0: printf("getservent failed");
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  Output
sl@0: @code
sl@0: Getservent passed
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: int main()
sl@0: {
sl@0: int stayopen=1;
sl@0: retservent(stayopen):
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @code
sl@0: #include<stdio.h>
sl@0: #include<netinet/in.h>
sl@0: #include<arpa/inet.h>
sl@0: #include<string.h>
sl@0: #include<netdb.h>
sl@0: int main()
sl@0: {
sl@0: struct servent *p;
sl@0:   p=getservent();
sl@0: if(p)
sl@0: endservent();
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: 
sl@0: Diagnostics:
sl@0:  Null pointer
sl@0: (0) returned on EOF or error. The getservent, getservbyport, getservbyname, setservent, and endservent functions appeared in BSD 4.2.
sl@0: 
sl@0: Bugs:
sl@0: 
sl@0:  These functions use a thread-specific data storage. If the data is needed 
sl@0: for future use it should be copied before any subsequent calls overwrite it. Expecting 
sl@0: port numbers to fit in a 32 bit quantity is probably naive. 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn getaddrinfo(const char *hostname, const char *servname,const struct addrinfo *hints, struct addrinfo **res)
sl@0: @param hostname
sl@0: @param servname
sl@0: @param hints
sl@0: @param res
sl@0: @return A zero return value for getaddrinfo() indicates successful completion; a non-zero return value indicates failure. The possible values for the failures are listed in the ERRORS section.
sl@0: Upon successful return of getaddrinfo(), the location to which res points shall refer to a linked list of addrinfo structures, each of which shall specify a socket address and information for use in creating a socket with which to use that socket address. 
sl@0: The list shall include at least one addrinfo structure. 
sl@0: 
sl@0: The freeaddrinfo() function shall free one or more addrinfo structures returned by getaddrinfo(), along with any additional storage associated with those structures. If the ai_next field of the structure is not null, the entire list of structures shall be freed. The freeaddrinfo() function shall support the freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo().
sl@0: 
sl@0: The getaddrinfo() function shall translate the name of a service location (for example, a host name) and//or a service name and shall return a set of socket addresses and associated information to be used in creating a socket with which to address the specified service.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  getnameinfo( const struct sockaddr * sa , socklen_t salen, char * host,size_t 
sl@0:       hostlen, char * serv, size_t servlen, int flags )
sl@0: @param sa
sl@0: @param salen
sl@0: @param host
sl@0: @param hostlen
sl@0: @param serv
sl@0: @param servlen
sl@0: @param flags
sl@0: @return   getnameinfo returns zero on success or one of the error codes listed in gai_strerror if an error occurs.
sl@0: 
sl@0: The getnameinfo function is used to convert a sockaddr structure to a pair of host name and service strings. It is a replacement for and provides more flexibility than the gethostbyaddr and getservbyport functions and is the converse of the getaddrinfo function. 
sl@0: The sockaddr structure sa should point to sockaddr_in (for IPv4) that is salen bytes long. 
sl@0: 
sl@0: The host and service names associated with sa are stored in host and serv which have length parameters hostlen and servlen. The maximum value for hostlen is NI_MAXHOST and the maximum value for servlen is NI_MAXSERV, as defined by \<netdb.h.\> If a length parameter is zero, no string will be stored. Otherwise, enough space must be provided to store the host name or service string plus a byte for the NUL terminator. 
sl@0: 
sl@0: The flags argument is formed by OR ’ing the following values: NI_NOFQDN  A fully qualified domain name is not required for local hosts. The local part of the fully qualified domain name is returned instead.  
sl@0: @code
sl@0: NI_NUMERICHOST  Return the address in numeric form, as if calling inet_ntop, instead of a host name.  
sl@0: NI_NAMEREQD  A name is required. If the host name cannot be found in DNS and this flag is set, a non-zero error code is returned. If the host name is not found and the flag is not set, the address is returned in numeric form.  
sl@0: NI_NUMERICSERV  The service name is returned as a digit string representing the port number.  
sl@0: NI_DGRAM  Specifies that the service being looked up is a datagram service, and causes getservbyport to be called with a second argument of "udp" instead of its default of "tcp." This is required for the few ports (512-514) that have different services for UDP and TCP.  
sl@0: @endcode
sl@0: 
sl@0: 
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <netdb.h>
sl@0: #include <netinet/in.h>
sl@0: int main()
sl@0: {
sl@0:      struct addrinfo *result;
sl@0:      char hostname[80];
sl@0:      int error;
sl@0:      if (error = getaddrinfo("www.yahoo.com",NULL, NULL, &result;))
sl@0:      {
sl@0:             fprintf(stderr, "error using getaddrinfo: %s
sl@0: ", gai_strerror(error));
sl@0:      }
sl@0:      if (result)
sl@0:      {
sl@0:             if (error = getnameinfo(result->ai_addr,result->ai_addrlen, hostname, sizeof(hostname), NULL,0,0))
sl@0:             {
sl@0:                    printf( "error using getnameinfo: %s
sl@0: ", gai_strerror(error));
sl@0:             }
sl@0:     }
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @see gai_strerror()
sl@0: @see getaddrinfo()
sl@0: @see inet_ntop()
sl@0: 
sl@0: 
sl@0: Caveats:
sl@0: 
sl@0:  getnameinfo can return both numeric and FQDN forms of the address specified in sa. There is no return value that indicates whether the string returned in host is a result of binary to numeric-text translation (like inet_ntop or is the result of a DNS reverse lookup.
sl@0: Because of this, malicious parties could set up a PTR record as follows:
sl@0: @code
sl@0: 1.0.0.127.in-addr.arpa. IN PTR  10.1.1.1
sl@0: 
sl@0: @endcode
sl@0:  and trick the caller of getnameinfo into believing that sa is 10.1.1.1
sl@0: when it is actually 127.0.0.1. To prevent such attacks, the use of NI_NAMEREQD is recommended when the result of getnameinfo is used
sl@0: for access control purposes:
sl@0: @code
sl@0: struct sockaddr *sa;
sl@0: socklen_t salen;
sl@0: char addr[NI_MAXHOST];
sl@0: struct addrinfo hints, *res;
sl@0: int error;
sl@0: error = getnameinfo(sa, salen, addr, sizeof(addr),
sl@0:     NULL, 0, NI_NAMEREQD);
sl@0: if (error == 0) {
sl@0:         memset(&hints;, 0, sizeof(hints));
sl@0:         hints.ai_socktype = SOCK_DGRAM; /*dummy*/
sl@0:         hints.ai_flags = AI_NUMERICHOST;
sl@0:         if (getaddrinfo(addr, "0", &hints;, &res;) == 0) {
sl@0:                 /* malicious PTR record */
sl@0:                 freeaddrinfo(res);
sl@0:                 printf("bogus PTR record
sl@0: ");
sl@0:                 return -1;
sl@0:         }
sl@0:         /* addr is FQDN as a result of PTR lookup */
sl@0: } else {
sl@0:         /* addr is numeric string */
sl@0:         error = getnameinfo(sa, salen, addr, sizeof(addr),
sl@0:             NULL, 0, NI_NUMERICHOST);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  
sl@0: Caveats:
sl@0: 
sl@0:  getnameinfo can return both numeric and FQDN forms of the address specified in sa. There is no return value that indicates whether the string returned in host is a result of binary to numeric-text translation (like inet_ntop or is the result of a DNS reverse lookup.
sl@0: Because of this, malicious parties could set up a PTR record as follows:
sl@0: @code
sl@0: 1.0.0.127.in-addr.arpa. IN PTR  10.1.1.1
sl@0: 
sl@0: @endcode
sl@0:  and trick the caller of getnameinfo into believing that sa is 10.1.1.1
sl@0: when it is actually 127.0.0.1. To prevent such attacks, the use of NI_NAMEREQD is recommended when the result of getnameinfo is used
sl@0: for access control purposes:
sl@0: @code
sl@0: struct sockaddr *sa;
sl@0: socklen_t salen;
sl@0: char addr[NI_MAXHOST];
sl@0: struct addrinfo hints, *res;
sl@0: int error;
sl@0: error = getnameinfo(sa, salen, addr, sizeof(addr),
sl@0:     NULL, 0, NI_NAMEREQD);
sl@0: if (error == 0) {
sl@0:         memset(&hints;, 0, sizeof(hints));
sl@0:         hints.ai_socktype = SOCK_DGRAM; /*dummy*/
sl@0:         hints.ai_flags = AI_NUMERICHOST;
sl@0:         if (getaddrinfo(addr, "0", &hints;, &res;) == 0) {
sl@0:                 /* malicious PTR record */
sl@0:                 freeaddrinfo(res);
sl@0:                 printf("bogus PTR record
sl@0: ");
sl@0:                 return -1;
sl@0:         }
sl@0:         /* addr is FQDN as a result of PTR lookup */
sl@0: } else {
sl@0:         /* addr is numeric string */
sl@0:         error = getnameinfo(sa, salen, addr, sizeof(addr),
sl@0:             NULL, 0, NI_NUMERICHOST);
sl@0: }
sl@0: 
sl@0: @endcode
sl@0:  
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  freeaddrinfo(struct addrinfo *ai)
sl@0: @param ai
sl@0: Refer to t() for the documentation
sl@0: @see bind()
sl@0: @see connect()
sl@0: @see send()
sl@0: @see socket()
sl@0: @see gai_strerror()
sl@0: @see gethostbyname()
sl@0: @see getnameinfo()
sl@0: @see getservent()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  gai_strerror(int ecode)
sl@0: @param ecode
sl@0: @return   The gai_strerror function
sl@0: returns a pointer to the error message string corresponding to ecode. If ecode is out of range, an implementation-specific error message string is returned.
sl@0: 
sl@0: @code
sl@0:  EAI_AGAIN temporary failure in name resolution
sl@0:  EAI_BADFLAGS
sl@0:   invalid value for ai_flags
sl@0:  EAI_BADHINTS
sl@0:   invalid value for hints
sl@0:  EAI_FAIL non-recoverable failure in name resolution
sl@0:  EAI_FAMILY ai_family not supported
sl@0:  EAI_MEMORY memory allocation failure
sl@0:  EAI_NONAME hostname or servname not provided, or not known
sl@0:  EAI_PROTOCOL
sl@0:   resolved protocol is unknown
sl@0:  EAI_SERVICE servname not supported for ai_socktype
sl@0:  EAI_SOCKTYPE
sl@0:   ai_socktype not supported
sl@0:  EAI_SYSTEM system error returned in errno
sl@0: 
sl@0: @endcode
sl@0:   The gai_strerror function returns an error message string corresponding to the error code
sl@0: returned by getaddrinfo or getnameinfo .
sl@0: 
sl@0:  The following error codes and their meaning are defined in \#include \<netdb.h\>
sl@0: 
sl@0:  EAI_AGAIN temporary failure in name resolution EAI_BADFLAGS  invalid value for ai_flags EAI_BADHINTS  invalid value for hints EAI_FAIL non-recoverable failure in name resolution EAI_FAMILY ai_family not supported EAI_MEMORY memory allocation failure EAI_NONAME hostname or servname not provided, or not known EAI_PROTOCOL  resolved protocol is unknown EAI_SERVICE servname not supported for ai_socktype EAI_SOCKTYPE  ai_socktype not supported EAI_SYSTEM system error returned in errno
sl@0: 
sl@0: Examples:
sl@0: @code
sl@0: #include <stdio.h>
sl@0: #include <netdb.h>
sl@0: #include <netinet/in.h>
sl@0: int main()
sl@0: {
sl@0:       struct addrinfo *result;
sl@0:       char hostname[80];
sl@0:       int error;
sl@0:       if (error = getaddrinfo("www.nokia.com",NULL, NULL, &result;))
sl@0:       {
sl@0:               fprintf(stderr, "error using getaddrinfo: %s
sl@0: ", gai_strerror(error));
sl@0:       }
sl@0:       if (result)
sl@0:       {
sl@0:               if (error = getnameinfo(result->ai_addr, sizeof(struct sockaddr), hostname, sizeof(hostname), NULL,0,0))
sl@0:               {
sl@0:                       printf( "error using getnameinfo: %s
sl@0: ", gai_strerror(error));
sl@0:               }
sl@0:       }
sl@0: return 0;
sl@0: }
sl@0: 
sl@0: @endcode
sl@0: @see getaddrinfo()
sl@0: @see getnameinfo()
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @fn  setservent(int f)
sl@0: @param f
sl@0: Refer to  getservent() for the documentation
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def h_errno
sl@0: 
sl@0: defines errno
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def _PATH_SERVICES
sl@0: 
sl@0: Defines the services path.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NETDB_INTERNAL
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). see errno.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NETDB_SUCCESS
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). No Problem.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def HOST_NOT_FOUND
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). Authoritative Answer Host not found.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def TRY_AGAIN
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). Non-Authoritative Host not found, or SERVERFAIL
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NO_RECOVERY
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). Non recoverable errors, FORMERR, REFUSED, NOTIMP
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NO_DATA
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). Valid name, no data record of requested type
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NO_ADDRESS
sl@0: 
sl@0: Error return codes from gethostbyname() and gethostbyaddr(). no address, look for MX record
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_AGAIN
sl@0: 
sl@0: Error return codes from getaddrinfo(). emporary failure in name resolution 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_BADFLAGS
sl@0: 
sl@0: Error return codes from getaddrinfo(). invalid value for ai_flags
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_FAIL
sl@0: 
sl@0: Error return codes from getaddrinfo(). non-recoverable failure in name resolution
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_FAMILY
sl@0: 
sl@0: Error return codes from getaddrinfo(). ai_family not supported 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_MEMORY
sl@0: 
sl@0: Error return codes from getaddrinfo(). memory allocation failure .
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_NONAME
sl@0: 
sl@0: Error return codes from getaddrinfo(). hostname nor servname provided, or not known.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_SERVICE
sl@0: 
sl@0: Error return codes from getaddrinfo(). servname not supported for ai_socktype.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_SOCKTYPE
sl@0: 
sl@0: Error return codes from getaddrinfo(). ai_socktype not supported 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_SYSTEM
sl@0: 
sl@0: Error return codes from getaddrinfo(). system error returned in errno.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_SOCKTYPE
sl@0: 
sl@0: Error return codes from getaddrinfo(). 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:  
sl@0: /** @def EAI_BADHINTS
sl@0: 
sl@0: Error return codes from getaddrinfo(). 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_PROTOCOL
sl@0: 
sl@0: Error return codes from getaddrinfo(). 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def EAI_MAX
sl@0: 
sl@0: Error return codes from getaddrinfo(). 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_PASSIVE
sl@0: 
sl@0: Flag values for getaddrinfo(). get address to use bind() 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_NUMERICHOST
sl@0: 
sl@0: Flag values for getaddrinfo(). prevent host name resolution
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_CANONNAME
sl@0: 
sl@0: Flag values for getaddrinfo(). fill ai_canonname
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_NUMERICSERV
sl@0: 
sl@0: Flag values for getaddrinfo(). prevent service name resolution 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_MASK
sl@0: 
sl@0: valid flags for addrinfo (not a standard def, apps should not use it) 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_ALL
sl@0: 
sl@0: IPv6 and IPv4-mapped (with AI_V4MAPPED) 
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_V4MAPPED_CFG
sl@0: 
sl@0: accept IPv4-mapped if kernel supports
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_ADDRCONFIG
sl@0: 
sl@0: only if any address is assigned
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_V4MAPPED
sl@0: 
sl@0: accept IPv4-mapped IPv6 address
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def AI_DEFAULT
sl@0: 
sl@0: special recommended flags for getipnodebyname
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_MAXHOST
sl@0: 
sl@0: Constants for getnameinfo()
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_MAXSERV
sl@0: 
sl@0: Constants for getnameinfo()
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_NOFQDN
sl@0: 
sl@0: Flag values for getnameinfo().
sl@0: Only the nodename portion of the FQDN is returned for local hosts.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_NUMERICHOST
sl@0: 
sl@0: Flag values for getnameinfo().
sl@0: The numeric form of the node's address is returned instead of its name.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_NAMEREQD
sl@0: 
sl@0: Flag values for getnameinfo().
sl@0: Return an error if the node's name cannot be located in the database.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_NUMERICSERV
sl@0: 
sl@0: Flag values for getnameinfo().
sl@0: The numeric form of the service address is returned instead of its name.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def NI_DGRAM
sl@0: 
sl@0: Flag values for getnameinfo().
sl@0: Indicates that the service is a datagram service (SOCK_DGRAM).
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @def SCOPE_DELIMITER
sl@0: 
sl@0: Scope delimit character
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @struct hostent
sl@0: 
sl@0: Structures returned by network data base library.  
sl@0: All addresses are supplied in host order, and returned in network order (suitable for use in system calls).
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var hostent::h_name
sl@0: official name of host
sl@0: */
sl@0: 
sl@0: /** @var hostent::h_aliases
sl@0: alias list 
sl@0: */
sl@0: 
sl@0: /** @var hostent::h_addrtype
sl@0: host address type
sl@0: */
sl@0: 
sl@0: /** @var hostent::h_length
sl@0: length of address
sl@0: */
sl@0: 
sl@0: /** @var hostent::h_addr_list
sl@0: list of addresses from name server
sl@0: */
sl@0: 
sl@0: /** @struct netent
sl@0: 
sl@0: Contains following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var netent::n_name
sl@0: official name of net
sl@0: */
sl@0: 
sl@0: /** @var netent::n_aliases
sl@0: alias list 
sl@0: */
sl@0: 
sl@0: /** @var netent::n_addrtype
sl@0: net address type
sl@0: */
sl@0: 
sl@0: /** @var netent::n_net
sl@0: network
sl@0: */
sl@0: 
sl@0: /** @struct servent
sl@0: 
sl@0: Includes following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var servent::s_name
sl@0: official service name
sl@0: */
sl@0: 
sl@0: /** @var servent::s_aliases
sl@0: alias list
sl@0: */
sl@0: 
sl@0: /** @var servent::s_port
sl@0:  port X
sl@0: */
sl@0: 
sl@0: /** @var servent::s_proto
sl@0: protocol to use 
sl@0: */
sl@0: 
sl@0: /** @struct protoent
sl@0: 
sl@0: Includes the following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var protoent::p_name
sl@0: official protocol name
sl@0: */
sl@0: 
sl@0: /** @var protoent::p_aliases
sl@0: alias list
sl@0: */
sl@0: 
sl@0: /** @var protoent::p_proto
sl@0: protocol X
sl@0: */
sl@0: 
sl@0: /** @struct addrinfo
sl@0: 
sl@0: Includes the following members,
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_flags
sl@0: AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST 
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_family
sl@0: PF_xxx
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_socktype
sl@0: SOCK_xxx 
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_protocol
sl@0: 0 or IPPROTO_xxx for IPv4 and IPv6
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_addrlen
sl@0: length of ai_addr
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_canonname
sl@0:  canonical name for hostname 
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_addr
sl@0: binary address
sl@0: */
sl@0: 
sl@0: /** @var addrinfo::ai_next
sl@0: next structure in linked list
sl@0: */
sl@0: 
sl@0: 
sl@0: /** @typedef  typedef __size_t	size_t
sl@0: 
sl@0: Used for sizes of objects.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @typedef  typedef __socklen_t	socklen_t
sl@0: 
sl@0: Socket address length type.
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: /** @typedef  typedef __uint32_t	uint32_t
sl@0: 
sl@0: Unsigned long int
sl@0: 
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: