Document revision date: 15 July 2002

The external integer h_errno is available only with OpenVMS Version 7.0, and is set only by a 4.4BSD TCP/IP interface. Specifically, The gethostbyname and gethostbyaddr functions require 4.4BSD semantics to set h_errno . The gethostbyname and gethostbyaddr functions indicate an error condition by returning a null pointer and setting the external integer h_errno to indicate the error return status.

When gethostbyname or gethostbyaddr returns an error status, h_errno , which is very similar to errno , can be checked to determine whether the error is the result of a temporary failure or an invalid or unknown host.

Use the herror routine to print the error message describing the failure. If the argument string to herror is not NULL, it is printed, followed by a colon (:) and a space. The error message is printed with a trailing new-line character.

The <netdb.h> header file declares h_errno on a per-thread basis as:

#define h_errno (*decc$h_errno_get_addr())

The <netdb.h> header file also symbolically defines the error code values that h_errno can accept, as follows:

HOST_NOT_FOUND	No such host is known.
TRY_AGAIN	Usually a temporary error that means the local server did not receive a response from an authoritative server. A retry at some later time can succeed.
NO_RECOVERY	An unexpected server failure is encountered. This is a nonrecoverable error.
NO_DATA	The requested name is valid but does not have an IP address; this is not a temporary error. The name is known to the name server but there is no address associated with this name. Another type of request to the name server using this domain name results in an answer; for example, a mail-forwarder registered for this domain.
NO_ADDRESS	No address; look for MX record

Like errno , the value of h_errno is zero at program startup. Checking h_errno is valid only when a failure status is returned by a Compaq C RTL routine that is defined to set it.

A.6 Relationship Between errno and h_errno

Since the routines that set h_errno can also set errno , this section explains the relationship between the two variables.

A given routine failure does not set both h_errno and errno for the same failure. A routine failure sets either h_errno or errno , depending on which is appropriate for the failing condition.

For example, consider the following program:

/* Demonstrate relationship between errno and h_errno */ /* from Appendix A of the reference manual */ #include <errno.h> #include <stdio.h> #include <netdb.h> main() { static char hostname[256]; struct hostent *hostentptr; errno = 0; h_errno = 0; if ((hostentptr = gethostbyname("hndy")) == NULL) { printf("unknown host name errno is: %d h_errno is: %d\n", errno, h_errn perror("p_gethostbyname"); herror("h_gethostbyname"); } errno = 0; h_errno = 0; if ((hostentptr = gethostbyname(0)) == NULL) { printf("illegal host name errno is: %d h_errno is: %d\n", errno, h_errn perror("p_gethostbyname"); herror("h_gethostbyname"); } }

In the first call to gethostbyname , the host name parameter "hndy" does not represent a known host. In this case, gethostbyname sets h_errno to HOST_NOT_FOUND , but does not set errno .

The call to perror in this example would output:

p_gethostbyname: Error 0

The call to herror in this example would print a message describing the failure:

h_gethostbyname: Unknown

In the second call to gethostbyname , the host name parameter is 0 (zero), an invalid argument. In this case, gethostbyname sets errno to EINVAL , but does not set h_errno .

A call to perror would print a message describing the failure:

p_gethostbyname: Invalid

A call to herror would print:

h_gethostbyname: Error 0

A.7 TCP/IP Interface Enhancements

The Compaq C RTL provides the language bindings for a 4.4BSD-compatible TCP/IP implementation. The underlying 4.4BSD semantics for the specific TCP/IP routines are the responsibility of the TCP/IP backend vendors.

With 4.4BSD semantics, gethostbyname and gethostbyaddr set the external variable h_errno . Other routines (see Table A-3) deal with 4.4BSD versions of the sockaddr and msghdr data structures. See the <socket.h> header file for a description of these structures.

The TCP/IP backend routines need to know the following:

• Whether gethostbyname and gethostbyaddr should set h_errno .
• What type of sockaddr and msghdr structures the Compaq C RTL is passing them---those defined by 4.4BSD systems, or those defined by pre-4.4BSD systems).

This information is controlled by the _SOCKADDR_LEN feature-test macro (see Section 1.5).

Compiling with _SOCKADDR_LEN defined will enable the entry points that have 4.4BSD semantics. See Table A-3. Otherwise, entry points expecting pre-4.4BSD semantics are enabled.

Table A-3 4.4BSD Entry Points

__bsd44_accept	__bsd44_gethostbyaddr	__bsd44_recvfrom
__bsd44_bind	__bsd44_gethostbyname	__bsd44_recvmsg
__bsd44_connect	__bsd44_getpeername	__bsd44_sendto
	__bsd44_getsockname	__bsd44_sendmsg

A.8 Summary of Socket Routines

This section groups and briefly describes the socket routines. For complete descriptions, see the routine reference section that follows in this appendix.

A.8.1 Basic Communication Routines

Table A-4 lists the basic communication routines that make up the building blocks of Internet programs.

Table A-4 Basic Communication Routines

Routine	Description
accept	Accepts a connection on a socket.
bind	Binds a name to a socket.
close	Closes a connection and deletes a socket descriptor.
connect	Initiates a connection on a socket.
ioctl	Controls socket operations only.
listen	Sets the maximum limit of outstanding connection requests for a socket.
read	Reads bytes from a file or socket and places them into a buffer.
readv	Not implemented.
recv	Receives bytes from a socket and places them into a buffer.
recvfrom	Receives bytes for a socket from any source.
recvmsg	Receives bytes from a socket and places them into scattered buffers.
select	Allows the polling or checking of a group of sockets.
send	Sends bytes through a socket to a connected peer.
sendmsg	Sends gathered bytes through a socket to any other socket.
sendto	Sends bytes through a socket to any other socket.
shutdown	Shuts down all or part of a bidirectional socket.
socket	Creates an endpoint for communication by returning a socket descriptor.
write	Writes bytes from a buffer to a file or socket.
writev	Not implemented.

A.8.2 Auxiliary Communication Routines

Table A-5 lists the auxiliary communication routines. These routines are used to provide information about a socket and to set the options on a socket.

Table A-5 Auxiliary Communication Routines

Routine	Description
getpeername	Returns the name of the connected peer.
getsockname	Returns the name associated with a socket.
getsockopt	Returns the options set on a socket.
setsockopt	Sets options on a socket.

A.8.3 h_errno Support Routines

Table A-6 lists the h_errno support routines. These routines map and write error-message strings generated by the external integer h_errno .

Table A-6 Supported h_errno Routines

Routine	Description
herror	Writes a message explaining a routine error.
hstrerror	Accesses message explaining routine errors.

A.8.4 Communication Support Routines

Table A-7 lists the communication support routines. These routines perform operations such as searching databases, converting byte order of network and host addresses, reading records, and returning Internet addresses.

Table A-7 Supported Communication Routines

Routine	Description
decc$get_sdc	Returns the socket device's OpenVMS I/O channel associated with a socket descriptor. vaxc$get_sdc and decc$get_sdc are synonyms for the same routine.
endhostent	Closes retrieval of network host entries and closes the network host file.
endnetent	Closes the networks database file.
endprotoent	Closes the protocols database file.
endservent	Closes the network services database file.
gethostaddr	Returns the standard host address for the processor.
gethostbyaddr	Searches the host database for a host record with a given address.
gethostbyname	Searches the host database for a host record with a given name or alias.
gethostname	Returns the name of the current host.
gethostent	Opens the network host entry by name from the network host database file.
getnetbyaddr	Searches the network database for a network record with a given address.
getnetbyname	Searches the network database for a network record with a given name or alias.
getnetent	Gets a network file entry from the networks database file.
getprotobyname	Searches the protocols database until a matching protocol name is found or until EOF is encountered.
getprotobynumber	Searches the protocols database until a matching protocol number is found or until EOF is encountered.
getprotoent	Gets a protocol database entry from the protocols database file.
getservbyname	Gets information on the named service from the network services database.
getservbyport	Gets information on the named port from the network services database.
getservent	Gets a services file entry from the network services database file.
hostalias	Searches for host aliases associated with a name.
htonl	Converts longwords from network to host byte order.
htons	Converts short integers from network to host byte order.
inet_addr	Converts Internet addresses in text form into numeric Internet addresses.
inet_lnaof	Returns the local network address portion of an Internet address.
inet_makeaddr	Returns an Internet address given a network address and a local address on that network.
inet_netof	Returns the Internet network address portion of an Internet address.
inet_network	Converts a null-terminated text string representing an Internet network address into a network address in network byte order.
inet_ntoa	Converts an Internet address into an ASCIZ (null-terminated) string.
ntohl	Converts longwords from host to network byte order.
ntohs	Converts short integers from host to network byte order.
sethostent	Opens, rewinds, and closes the network host database file.
setnetent	Opens, rewinds, and closes the networks database file.
setprotoent	Opens, rewinds, and closes the protocols database file.
setservent	Opens, rewinds, and closes the network services database file.
decc$socket_fd	Returns the socket descriptor associated with a Socket Device Channel for direct use with the Compaq C RTL.
vaxc$get_sdc	Returns the socket device's OpenVMS I/O channel associated with a socket descriptor. vaxc$get_sdc and decc$get_sdc are synonyms for the same routine.

A.8.5 IPv6 Routines

Table A-8 lists the IPv6 socket routines supported by the C RTL. For more information on IPv6 features and routines, see the TCP/IP Services for OpenVMS product documentation.

Table A-8 IPv6 Routines

Routine	Description
if_freenameindex	Frees dynamic memory allocated by if_nameindex to the array of interface names and indexes.
if_indextoname	Maps an interface index to its corresponding name.
if_nameindex	Returns an array of all interface names and indexes.
if_nametoindex	Maps an interface name to its corresponding index.
freeaddrinfo	Returns addrinfo structures and dynamic storage to the system.
freehostent	Deprecated routine. Replace with freeaddrinfo .
gai_strerror	Describes an error value for the getaddrinfo and getnameinfo functions.
getaddrinfo	Protocol-independent function for mapping names to addresses.
getipnodebyname	Deprecated routine. Replace with getnameinfo .
getipnodebyaddr	Deprecated routine. Replace with getaddrinfo .
getnameinfo	Protocol-independent function for mapping addresses to names.
inet_aton	Converts a string to an Internet address stored in a structure. Obsoletes the inet_addr function.
inet_ntop	Converts a numeric address to a text string suitable for presentation.
inet_pton	Converts an address in its standard text presentation form to its numeric binary form, in network byte order.

	privacy and legal statement
5763PRO_066.HTML