TCP/IP for DOS Socket Library Reference
Appendix A. Socket Library Functions
This appendix describes the functions in the DOS and Windows Socket Libraries and provides a detailed description of each function. All function calling conventions are consistent with the 4.3BSD socket interface standards.
In this appendix, the functions are listed alphabetically. The majority of the functions are the same in both the DOS and Windows libraries. Because the Windows library uses a dynamic link library (DLL), the Windows functions have some different declarations of pointer variables and structures. For example, the Windows functions use far pointers, and do not have access to global variables. In most cases, these differences do not result in different capabilities. For detailed information about DLL data space and memory usage, refer to your compiler documentation.
Where functions or capabilities within functions are available in only one of the two libraries, this information is clearly noted. Refer to Chapter 4, "Functions by Category," for a list of the library functions arranged by type.
NOTE: When a function has both synchronous and asynchronous versions, they are listed under one entry. The asynchronous version has the suffix "_anr." The include files are the same for the two versions. The calling conventions and parameter list for the synchronous function are presented first, followed by the asynchronous function. The Description and Return Value sections explain any differences between parameters and usage for the two functions.
Function naming conventions follow the C runtime library conventions and the Windows library conventions. Low-level functions that are called by other functions have names that begin with an underbar (for example, _abort_oper()). Windows library function names use both uppercase and lowercase letters.
Asynchronous versions of functions cannot be used in programs that run under standard mode in Windows or under DESQview. The Windows socket library functions are compatible only with Microsoft Windows v3.0 and v3.1.
Alphabetical list of Functions:
NOTE: The _abort_oper() function is available only in the DOS Socket Library.
Example A-1 illustrates the _abort_oper() syntax.
_abort_oper() Syntax
Description
The _abort_oper() function terminates a blocking socket library function when the program receives the SIGINT interrupt signal. The interrupt signal could be generated by pressing <Ctrl-C> or <Ctrl-Break> on the keyboard, or by sending SIGINT from another program.
This function must be included in the function that handles the SIGINT interrupt signal. The handler for the interrupt signal could have the form illustrated in Example A-2.
SIGINT Interrupt Handler
break_handler() { ... abort_oper(); signal (SIGINT, break_handler); ...}
When a SIGINT interrupt signal occurs, the interrupt handler function is called. The interrupt handler function in turn calls the _abort_oper() function. It terminates any blocking socket library function that is currently executing. The blocking function returns the error code EINTR. The functions that are terminated by the _abort_oper() function and return EINTR are listed in Tables 4-1 and 4-2 in Chapter 4. If no blocking function from the socket library is executing at the time when the program receives the interrupt signal, the _abort_oper() function does nothing.
To handle a software interrupt generated by pressing <Ctrl-C> on the keyboard, the program must set the variable break_enabled to a nonzero value. This variable should be set before any blocking call that might need to be interrupted by an interrupt signal. Because pressing <Ctrl-Break> generates a hardware interrupt, the interrupt handler function is called whether or not break_enabled is set.
Example A-3 illustrates the accept() and accept_anr() syntax.
accept() and accept_anr() Syntax
Description
The accept() and accept_anr() functions accept a connection on a socket. This function is used only with the connection-based socket type, SOCK_STREAM.
The s parameter is a socket descriptor for a socket that has been created with the socket() function, bound to an address with the bind() function, and is listening for connections after a listen() function call. The accept() and accept_anr() functions extract the first connection on the queue of pending connections, create a new socket with the same properties as s, and allocate a new descriptor ns for the socket. The accepted socket ns cannot be used to accept more connections. The original socket s remains open, and can be used to accept more connections.
The addr parameter is a result parameter that receives the address of the connecting host, as known to the communications layer. The exact format of the addr parameter is specified by the sockaddr address structure, described in Chapter 3. The addrlen parameter is a value-result parameter and should initially contain the amount of space pointed to by addr. On return it contains the actual length (in bytes) of the address returned.
The accept() function returns the new descriptor, ns, for the socket. If no pending connections are present on the queue and the socket is not marked as nonblocking, accept() blocks execution of the program until a connection is present. If the socket is marked nonblocking and no pending connections are present on the queue, accept() returns the error EWOULDBLOCK.
It is possible to determine when a socket is ready to perform an accept() by using select() to check whether it is readable.
The accept_anr() function accepts connections on a socket asynchronously. This function differs from accept() in that it initiates a connection acceptance operation and immediately returns control to the caller. When the connection acceptance operation terminates, either successfully or unsuccessfully, the socket library updates the result, addr, and addrlen parameters, and calls the user-supplied function post_routine(). The result parameter is a pointer to an integer that receives the result of the operation, either the new socket descriptor or a negative error value.
The post_routine parameter is the address of a user-supplied function that is called upon completion of the accept_anr() function. The accept_anr() function passes two parameters, usercb and error_code, to the post_routine() function. The usercb parameter is a user-supplied value that can be used to distinguish among multiple outstanding requests to the same post_routine. The error_code parameter contains a value from SOCKET.H that indicates the type of error if there was an error. If there was no error, it has the value EOK (0).
Return Value
A successful accept() returns a positive integer representing the newly accepted socket descriptor. An unsuccessful accept() returns -1 and stores a code for the encountered error in the global variable errno (directly accessible to DOS applications). Windows applications can use GetErrno() to determine which error occurred.
A successful accept_anr() returns 0 to the caller in immediate_result. This return indicates that the operation is in progress and the caller's post_routine() function will be called upon completion. Upon completion of an accept_anr() call, the result field contains a positive value representing the new socket descriptor, or a negative error value if the operation failed. It stores a code for the encountered error in the global errno variable and in the error_code variable, which it passes to the caller's post_routine() function.
An unsuccessful accept_anr() call returns a negative value in immediate_result and stores a code for the encountered error in the global variable errno (directly accessible to DOS applications). Windows applications can use GetErrno() to determine which error occurred.
Errors
The accept() or accept_anr() functions fail if one or more of the following errors occur:
EASYNCNOTSUPP
The requested asynchronous operation cannot be performed. This error occurs when DOS applications run under standard mode in Windows or under DESQview and request asynchronous services .
EBADF
The socket descriptor is not valid.
ECONNABORTED
A connection was aborted before being accepted.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL
The value of addrlen was less than the size of the sockaddr structure.
ENO_RCB
The library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
EOPNOTSUPP
The referenced socket is not of type SOCK_STREAM.
EWOULDBLOCK
The socket is marked nonblocking and no connections are present to be accepted.
Example A-4 illustrates the syntax for these functions.
bcmp(), bcopy(), and bzero() Syntax
Description
The bcopy(), bcmp(), and bzero() functions operate on strings of bytes with variable lengths. They do not check for null bytes.
The bcopy() function copies length bytes from the src string to the dst string.
The bcmp() function compares byte string bl against byte string b2. It returns zero if they are identical, and nonzero otherwise. Both strings are assumed to be length bytes long.
The bzero() function places 1ength bytes of null (0) in the b string.
Return Value
The bcmp() function returns zero if the two strings are identical, and nonzero otherwise.
Example A-5 illustrates the bind() syntax.
bind() Syntax
Description
The bind() function assigns a name to an unnamed socket. When a socket is created with socket(), it exists in a name space (address family) but has no name assigned; bind() assigns name to the socket.
Notes
The rules used in name binding are the same for both TCP and UDP sockets. The members of the
sockaddr structure that name points to must be as follows:
If specified, the local IP address must be a valid Internet address for the host. If the IP address is specified as 0, a valid IP address is provided. If the port number is specified as 0, an unused port number above 1024 is provided.
Return Value
If the bind operation is successful, the bind() function returns a 0; otherwise, the bind() function returns -1 and stores a more specific error code in the global variable errno (directly accessible to DOS applications). Windows applications can use GetErrno() to determine which error occurred.
Errors
The bind() function fails if any of the following conditions occur:
EADDRINUSE
The specified address is already in use.
EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
EBADF
The s value is not a valid socket descriptor.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL
The socket is already bound to an address or the value of namelen is less than the size of the sockaddr structure.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-6 illustrates the connect() and connect_anr() syntax.
connect() and connect_anr() Syntax
Description
The connect() and connect_anr() functions initiate a connection on a socket.
The s parameter is a socket descriptor returned by socket(). If s has not been assigned a local address using the bind() function, connect() or connect_anr() assigns one. If the socket is of type SOCK_DGRAM, these calls specify the peer with which the socket is to be associated; this address is where datagrams are to be sent, and the only address from which datagrams are to be received. If the socket is of type SOCK_STREAM, these calls attempt to make a connection to another socket. The other socket is specified by name, an address in the PF_INET domain. The exact format of the sockaddr structure referenced by name is described in Chapter 3.
The members of the sockaddr structure that must be filled (in network byte order) are as follows:
Generally, stream sockets can successfully establish a connection with these functions only once; datagram sockets can use these functions multiple times to change their association dynamically. Datagram sockets can dissolve the association by connecting to an invalid address, such as a null address.
The connect_anr() function initiates connections on a socket asynchronously. This function differs from the connect() function in that it initiates a connection operation and immediately returns control to the caller. When the connection acceptance operation terminates, either successfully or unsuccessfully, the socket library updates the result field and calls the user-supplied function post_routine(). The result parameter is a pointer to an integer that receives the result, either the new socket descriptor or a negative error value. The post_routine parameter is the address of a user-supplied function that is called upon completion of the connect_anr() function.
The connect_anr() function passes two parameters, usercb and error_code, to the post_routine() function. The usercb parameter is a user-supplied value that can be used to distinguish among multiple outstanding requests to the same post_routine() function. The error_code parameter contains a value from SOCKET.H indicating the type of error if there was an error. If there was no error, it has the value EOK (0).
Return Value
If connect() succeeds with the connection or binding, it returns 0; otherwise, connect() returns -1 and stores a code for the encountered error in the global variable errno. (The errno variable is directly accessible in the DOS library; in the Windows library use GetErrno() to access the error value from the DLL).
A successful connect_anr() returns 0 to the caller to indicate that the operation is in progress and the caller's post_routine() will be called upon completion. Upon completion of a connect_anr() function, the result field contains 0 to indicate successful connection or binding, or a negative error value if the operation failed. The function stores a code for the encountered error in the global errno variable (DOS library) or the errno variable internal to the DLL (Windows library), and in the error_code variable, which it passes to the caller's post_routine() function.
An unsuccessful connect_anr() returns a negative value in immediate_result and stores a code for the encountered error in the global variable errno. (The errno variable is directly accessible in the DOS library; in the Windows library use GetErrno() to access the error value from the DLL).
Errors
The connect() or connect_anr() call fails if one or more of the following conditions exist:
EADDRINUSE
The address is already in use.
EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
EALREADY
The connect operation is currently in progress.
EASYNCNOTSUPP
The requested asynchronous operation cannot be performed. This error occurs when DOS applications run under standard mode in Windows or under DESQview and request asynchronous services.
EBADF
The s value is not a valid socket descriptor.
ECONNREFUSED
The attempt to connect was rejected.
EINPROGRESS
The connect operation is in progress.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL
The value of namelen is less than the size of sockaddr.
EISCONN
The socket is already connected.
ENO_RCB
The library has run out of internal resources because there are too many outstanding socket
function calls.
ENOTINSTLD
The requested protocol is not installed.
ETIMEDOUT
Connection establishment timed out without establishing a connection.
Example A-7 illustrates the dn_comp() syntax.
dn_comp() Syntax
Description
The dn_comp() function compressed the domain name exp_dn and stores it in the array comp_dn. If the function concludes successfully, it returns the size of the compressed name. If errors occur, the function returns -1. The length parameter contains the length of the comp_dn array. The dnptrs parameter is a list of pointers to previously compressed names in the last message sent or received. The first pointer in the list points to the beginning of the message. The list ends with a NULL character. The lastdnptr parameter points to the end of the list. The dn_comp() function also updates the list of pointers for labels inserted into the message as the domain name exp_dn is compressed. If dnptrs is NULL, the function does not compress exp_dn. If lastdnptr is NULL, the function does not update the list.
Name servers typically return many names in answer to a query, and often the suffixes of these names are common to all of the names. The dn_comp() function saves space in messages by storing a single copy of duplicated domain name elements.
Return Value
The function returns the size of the compressed name if it terminates successfully, or -1 if there were errors.
Files
\NET\TCP\RESOLV.CFG
Example A-8 illustrates the dn_expand() syntax .
dn_expand() Syntax
Description
The dn_expand() function expands the compressed domain name comp_dn to a full domain name. Expanded names are converted to all uppercase letters. The msg parameter points to the beginning of the message. The exp_dn parameter points to a buffer of size length for the result. The eomorig parameter points to the first position of the next message location after the current message. The return_value parameter contains the length of the compressed name if the function concludes successfully or -1 if an error occurs.
Name servers typically return many names in answer to a query, and often the suffixes of these names are common to all of the names. The dn_expand() function converts partial names to full domain names.
Return Value
If the function concludes successfully, return_value contains the length of the compressed name. If an error occurs, return_value contains -1.
NOTE: These functions are available only in the Windows Socket Library and are included for reference.
Example A-9 illustrates the syntax for these functions.
GetErrno(), GetDNSErrno(), and GetHErrno() Syntax
Description
The basic structure of dynamic link libraries prevents the definition of global variables accessible by library users. These functions allow users to access error codes maintained in variables in the Windows dynamic link library, WLIBSOCK.DLL.
The GetErrno() function accesses the value of the errno variable in the Windows dynamic link library.
The GetDNSErrno() function accesses the value of the dns_errno variable in the Windows dynamic link library.
The GetHErrno() function accesses the value of the h_errno variable in the Windows dynamic link library.
Return Value
The GetErrno() function returns a positive integer value representing the current value of errno.
The GetDNSErrno() function returns a positive integer value representing the current value of dns_errno
The GetHErrno() function returns a positive integer value representing the current value of h_errno.
Example A-10 illustrates the syntax for these functions.
gethostbyaddr() and gethostbyname() Syntax
Description
NOTE: The operations performed by the gethostent(), sethostent(), and endhostent() function in previous versions of the NetWare Communication Services are now performed automatically when you call the gethostbyname() and gethostbyaddr() functions. If your program calls gethostent(), sethostent(), or endhostent(), the NO_RECOVERY error is returned in the errno variable.
The gethostbyname() and gethostbyaddr() functions return a pointer (DOS library) or a global variable HANDLE (Windows library) to a hostent structure containing separate fields from a line in the HOSTS file.
The gethostbyname() function accepts a pointer to a character string representing a hostname to search for in the HOSTS file.
The gethostbyaddr() function accepts a pointer to a long integer representing the numeric Intemet address, an integer value representing the Intemet address length, and an integer type value. (The numeric Internet address is expressed in network byte order; the Intemet address length is expressed in bytes.)
The sequence of directories to search to locate the HOSTS file is determined by the PATH TCP_CFG setting under the Protocol TCPIP section heading in the workstation's NET.CFG file. This path is read once by the TCP/IP transport driver, when it is loaded into memory, and is then maintained in memory for use by these functions. The functions search each HOSTS file in the path until the specified entry is found or the end of the path is reached.
DOS Library hostent Structure
In the DOS library, the hostent structure returned by these functions resides in static library storage and is replaced by the next use of gethostbyname() or gethostbyaddr(), The DOS library hostent structure has the format illustrated in Example A-11.
DOS Library hostent Structure
The members of the DOS library hostent structure are as follows:
Windows Library hostent Structure
In the Windows library, the application program is responsible for locking, unlocking, and freeing the global HANDLES required by these functions. The Windows library hostent structure is illustrated in Example A-12.
Windows Library hostent Structure
The members of the Windows library hostent structure are as follows:
Parameters
| h_errno | Error value set by gethostbyname() or gethostbyaddr(). |
| name | Official name of the host. |
| addr | Internet address of the host. |
| len | Length of the Internet address, in bytes. |
| type | Value corresponding; to the type of Internet address. Currently, type is always PF_INET. |
DOS Library Return Value
The gethostbyname() and gethostbyaddr() functions return a null pointer when an error occurs.
The global variable h_errno can then be checked to determine the nature of the error.
Windows Library Return Value
The gethostbyname() and gethostbyaddr() calls return a null HANDLE when an error occurs. The application can then use the GetHErrno() function to determine the error value in the h_errno variable in the DLL.
Errors
The variable h_errno can have the following values:
HOST_NOT_FOUND
No such host exists in any HOSTS file in the search path.
NO_RECOVERY
This is a nonrecoverable error.
Files
\NET\TCP\HOSTS
Example A-13 illustrates the getmyipaddr() syntax.
getmyipaddr() Syntax
Description
The getmyipaddr() function takes no parameters and returns the IP address of the local system as a long integer.
Return Value
The getmyipaddr() function returns the local IP address or -1 if there was an error. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-14 illustrates the getmymacaddr() syntax.
getmymacaddr() Syntax
Description
The getmymacaddr() function gets the address of the local Medium Access Control (MAC) device.
The user supplies the address of a buffer in macaddrp and a pointer to the length of the buffer in macaddrlen. The getmymacaddr() function returns the local MAC address in macaddrp using network byte order and updates macaddrlen with the length of the value returned.
Return Value
If successful, getmymacaddr() returns 0. If it is unsuccessful, it returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EINVAL
The value of the macaddrlen parameter is less than 6.
ENO_RCB
The library has run out of internal resources because there are too many outstanding socket
function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-15 illustrates the syntax for these functions .
getnetbyaddr() an getnetbyname() Syntax
Description
NOTE: The operations performed by the getnetent(), setnetent(), and endnetent() functions in previous versions of the NetWare Communication Services are now performed automatically when you call the getnetbyname() and getnetbyaddr() functions. if your program calls getnetent(), setnetent(), or endnetent(), the NO_RECOVERY error is returned in the errno variable.
The getnetbyaddr() and getnetbyname() functions each return a pointer (DOS library) or a global HANDLE (Windows library) to a netent structure containing separate fields from a line in the NETWORKS file.
The getnetbyaddr() function sequentially searches from the beginning of the NETWORKS file until a matching network address and network number type are found, or until the end of the file is reached. The getnetbyname() function sequentially searches from the beginning of the NETWORKS file until a matching network name and network number type are found, or until the end of the file is reached. Both functions return network numbers in host byte order.
The getnetbyname() function accepts a pointer to a character string representing a network name to search for. The getnetbyaddr() function accepts a pointer to a long integer value representing the numeric Internet network number in network byte order, and an integer type value.
The sequence of directories to search to locate the NETWORKS file is determined by the PATH TCP_CFG setting under the Protocol TCPIP section heading in the workstation's NET.CFG file. This path is read once by the TCP/IP transport driver, when it is loaded into memory, and is then maintained in memory for use by these functions. The functions search each NETWORKS file in the path until the specified entry is found or the end of the path is reached.
DOS Library netent Structure
In the DOS library, the netent structure returned by these functions resides in static library storage. The next use of getnetbyaddr() or getnetbyname() replaces the structure.
The DOS library netent structure has the format illustrated in Example A-16.
DOS Library netent Structure
The members of this structure are as follows:
Windows Library netent Structure
In the Windows library, your application program is responsible for locking, unlocking, and freeing the global HANDLES returned by these functions. The Windows library netent structure has the format illustrated in Example A-17.
Windows Library netent Structure
The members of this structure are as follows:
Parameters
| name | Official name of the network. |
| net | Internet number of the network. |
| type | Value corresponding to the network type. Currently, the only network type supported is PF_INET. |
DOS Library Return Value
The getnetbyname() and getnetbyaddr() functions return a null pointer when an error occurs. The global variable h_errno can then be checked to determine the nature of the error.
Windows Library Return Value
The getnetbyname() and getnetbyaddr() calls return a null HANDLE when an error occurs. The application can then use the GetHErrno() function to determine the error value in the h_errno variable in the DLL.
Errors
The variable h_errno can have the following values:
NET_NOT_FOUND
No such network exists in any NETWORKS file in the search path.
NO_RECOVERY
This is a nonrecoverable error.
Files
\NET\TCP\NETWORKS
Example A-18 illustrates the getpeername() syntax.
getpeername() Syntax
Description
The getpeername() function sets name to the current name, as represented by a sockaddr structure, of the peer connected to the specified socket s. The namelen parameter should be initialized to indicate the amount of space pointed to by name, which should be sizeof(struct sockaddr). On return, namelen contains the actual size (in bytes) of the name determined by the getpeername() function. The name is truncated if the buffer provided is too small.
Return Value
If successful, getpeername() returns 0. If it is unsuccessful, it returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EBADF
The s parameter is not a valid socket descriptor.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL (DOS library only)
The value of namelen is less than the size of the sockaddr structure.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTCONN
The socket is not connected.
ENOTINSTLD
The requested protocol is not installed.
Files
\NET\TCP\NETWORKS
Example A-19 illustrates the syntax for these functions.
getprotobyname() and getprotobynumber() Syntax
Description
NOTE: The operations performed by the getprotoent(), setprotoent(), and endprotoent() functions in previous versions of the NetWare Communication Services are now performed automatically when you call the getprotobyname() and getprotobynumber() functions. If your program calls getprotoent(), setprotoent(), or endprotoent(), the NO_RECOVERY error is returned in the errno variable.
The getprotobyname() and getprotobynumber() functions each return a pointer (DOS library) or a global HANDLE (Windows library) to a protoent structure containing separate fields from a line in the PROTOCOL file in the \NET\TCP directory. (This filename differs from the 4.3BSD filename protocols due to the 8-character filename limitation imposed by DOS.)
The getprotobyname() and getprotobynumber() calls sequentially search from the beginning of the PROTOCOL file until a matching protocol name or protocol number is found, or until they reach the end of the file.
The getprotobyname() function accepts a pointer to a character string representing a protocol name to find. The getprotobynumber() function accepts an integer protocol number.
The sequence of directories to search to locate the PROTOCOL file is determined by the PATH TCP_CFG setting under the Protocol TCPIP section heading in the workstation's NET.CFG file. This path is read once by the TCP/IP transport driver, when it is loaded into memory, and is then maintained in memory for use by these functions. The functions search each PROTOCOL file in the path until the specified entry is found or the end of the path is reached.
DOS Library protoent Structure
In the DOS library, the protoent structure returned by these functions resides in static library storage. The next use of getprotobyname() or getprotobynumber() replaces the structure. The DOS library protoent structure has the format shown in Example A-20.
DOS Library protoent Structure
The members of this structure are as follows:
Windows Library protoent Structure
In the Windows library, your application program is responsible for locking, unlocking, and freeing the global HANDLES returned by these functions.
The Windows library protoent structure has the format shown in Example A-21.
Windows Library protoent Structure
The members of this structure are as follows:
Parameters
| name | Official name of the protocol. |
| proto | Protocol number. |
DOS Library Return Value
The getprotobyname() and getprotobynumber() functions return a null pointer in result when an error occurs. The global variable h_errno can then be checked to determine the nature of the error.
Windows Library Return Value
The getprotobyname() and getprotobynumber() calls return a null HANDLE when an error occurs. The application can then use the GetHErrno() function to determine the error value in the h_errno variable in the DLL.
Errors
The variable h_errno can have the following values:
PROTO_NOT_FOUND
No such protocol exists in any PROTOCOL file in the search path.
NO_RECOVERY
This is a nonrecoverable error.
Files
\NET\TCP\PROTOCOL
Example A-22 illustrates the syntax for these functions.
getservbyname() and getservbyport() Syntax
Description
NOTE: The operations performed by the getservent(), setservent(), and <skip>()functions in previous versions of the NetWare Communication Services are now performed automatically when you call the getservbyname() and getservbyport() functions. if your program calls getservent(), setservent(), or endservent(), the NO_RECOVERY error is returned in the errno variable.
The getservbyname() and getservbyport() functions each return a pointer (DOS library) or a global HANDLE (Windows library) to a servent structure containing separate fields from a line in the SERVICES file.
The getservbyname() and getservbyport() functions sequentially search from the beginning of the SERVICES file until a matching protocol name or port number is found, or until the end of the file is reached. If a protocol name is also supplied, searches must also match the specified protocol .
The getservbyname() function accepts pointers to two character strings representing the service and protocol name to find.
The getservbyport() function accepts a pointer to a character string representing the protocol name and an integer representing the port number in network byte order.
The sequence of directories to search to locate the SERVICES file is determined by the PATH TCP_CFG setting under the Protocol TCPIP section heading in the workstation's NET.CFG file. This path is read once by the TCP/IP transport driver, when it is loaded into memory, and is then maintained in memory for use by these functions. The functions search each SERVICES file in the path until the specified entry is found or the end of the path is reached.
DOS Library servent Structure
In the DOS library, the servent structure returned by these functions resides in static library storage and is overwritten by the next call to getservbyname() or getservbyport().
The DOS library servent structure has the format illustrated in Example A-23.
DOS Library servent Structure
The members of this structure are as follows:
Windows Library servent Structure
In the Windows library, your application program is responsible for locking, unlocking, and freeing the global HANDLES returned by these functions.
The Windows library servent structure has the format illustrated in Example A-24.
Windows Library servent Structure
The members of this structure are as follows:
Parameters
| name | Official name of the service. |
| proto | Name of protocol to use when contacting the service. |
| port | Port number at which the service resides, in network byte order. |
DOS Library Return Value
The getservbyname() and getservbyport() functions return a null pointer in result when an error occurs. The global variable h_errno can then be checked to determine the nature of the error.
Windows Library Return Value
The getservbyname() and getservbyport() calls return a null HANDLE when an error occurs. The application can then use the GetHErrno() function to determine the error value in the h_errno variable in the DLL.
Errors
The variable h_errno can have the following values:
SERV_NOT_FOUND
No such service exists in any SERVICES file in the search path.
NO_RECOVERY
This is a nonrecoverable error.
Files
\NET\TCP\SERVICES
Example A-25 illustrates the getsockname() syntax.
getsockname() Syntax
Description
The getsockname() function sets name to the current name, as represented by a sockaddr structure, of the specified socket s. The namelen parameter should be initialized to indicate the amount of space pointed to by name, and on return it contains the actual size of the name returned (in bytes), both of which are sizeof(struct sockaddr) in the PF_INET address family. The members of name are returned as bound by the bind() function. Refer to bind() for a description of these fields.
Return Value
If successful, getsockname() returns 0. If it is unsuccessful, it returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EBADF
The s value is not a valid socket descriptor.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL (DOS library only)
The value of namelen is less than the size of the sockaddr structure.
ENO_RCB
The library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-26 illustrates the getsockopt() syntax.
getsockopt() Syntax
Description
The getsockopt() function returns the status of options for a specified socket s. Options do not currently exist at multiple protocol levels; they are only provided at the uppermost socket level.
NOTE: The parameter level must be specified as SOL_SOCKET.
The parameters optval and optlen identify a buffer in which the values for the requested options are returned. The optlen parameter is a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on return to indicate the actual size of the value returned.
The optname parameter specifies the socket option. The include file SOCKET.H contains definitions for socket-level options as described below.
Most socket-level options take an int parameter for optval. In general, options that can be set on or off are enabled with an optval of 1 and disabled with an optval of 0.
The following options are recognized at the socket level. Each can be examined with getsockopt().
SO_KEEPALIVE
Examine the current keep-alive option state (enabled or disabled).
SO_REUSEADDR
Examine the current state of the reuse-local-address option (enabled or disabled).
The SO_KEEPALIVE option enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken. If the option is set, optval gets a nonzero value; otherwise, it has the value 0.
The SO_REUSEADDR option indicates to the bind() function that it can use addresses already in use. If this option is set, optval returns a nonzero value; otherwise, it returns a value of 0.
Return Value
If successful, getsockopt() returns 0. If it is unsuccessful, it returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EBADF
The s value is not a valid socket descriptor.
EINVAL (DOS library only)
The value of optlen is not the required size for optval.
ENOPROTOOPT (DOS library only)
The option is unknown at the level indicated.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-27 illustrates the syntax for these functions.
htonl(), htons(), ntohl(), and ntohs() Syntax
Description
These functions convert 16-bit and 32-bit quantities from network byte order to host byte order, and vice versa, as follows:
These functions are frequently used to convert Internet addresses and ports returned by the gethostbyname() function to native byte order.
Parameters
| hostlong | A 32-bit quantity in host byte order |
| hostshort | A 16-bit quantity in host byte order |
| netlong | A 32-bit quantity in network byte order |
| netshort | A 16-bit quantity in network byte order |
Return Value
These functions return a value that has been converted from network to host or from host to network order.
Example A-28 illustrates the syntax for these functions.
inet_addr(), inet_network(), inet_ntoa(), inet_makeaddr(), inet_inaof(), and inet_netof() Syntax
Description
The inet_addr() and inet_network() functions each interpret character strings representing numbers expressed in the Internet standard dotted notation, returning numbers that can be used as Internet addresses and Internet network numbers, respectively.
The inet_ntoa() function converts an Internet address into an ASCII string representing the address in dotted notation. In the Windows library version of this function, the pointer cp must point to a buffer long enough to hold the ASCII representation of the address. The Windows function sets the variable result_value to point to the buffer pointed to by cp.
The inet_makeaddr() function takes an Internet network number and a local network address and constructs an Internet address from them.
The inet_netof() and inet_lnaof() functions separate Internet host addresses, returning the network number and local network address part, respectively.
All Internet addresses are returned in network order (bytes ordered from left to right). All network numbers and local address parts are returned as machine-format long values (as opposed to a character representation of a long value).
Parameters
| cp | Character string that represents the Internet address |
| in | Internet address, in standard dotted notation. |
| net | Internet network number. |
| lna | Local network address part of an Internet address. |
Internet Addresses
Values specified using dotted notation take one of the following forms:
When only one part is given, the value is stored directly in the network address without any byte rearrangement.
When a two-part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the rightmost three bytes of the network address. This makes the two-part address format convenient for specifying Class A network addresses, for example, net.host.
When a three-part address is specified, the last part is interpreted as a 16-bit quantity and placed in the rightmost two bytes of the network address. This makes the three-part address format convenient for specifying Class B network addresses, for example, 128.net.host.
When four parts are specified, each part is interpreted as a byte of data and assigned, from left to right, to the 4 bytes of an Internet address.
All numbers supplied as parts in dotted notation can be expressed in decimal, octal, or hexadecimal, as specified in the C language. (A leading Ox or OX designates a hexadecimal number, or a leading 0 followed directly by digits designates an octal number; otherwise, the number is interpreted as decimal.)
Return Value
The value -1 is returned by inet_addr() and inet_network() upon detection of malformed requests. These functions do not update the errno variable. The functions inet_ntoa(), inet_makeaddr(), inet_lnaof(), and inet_netof() do not return error values.
Files
\NET\TCP\HOSTS\NET\TCP\NETWORKS
Example A-29 illustrates the ioctl() syntax.
ioctl() Syntax
Description
The ioctl() function performs a variety of functions on open socket descriptors.
The request parameter can take the value of the following macros and symbolic constants, as defined in SOCKET.H:
FIONREAD /* get # bytes to read */ FIONBIO /* set/clear nonblocking I/O */
The argp parameter is a pointer to an integer for FIONREAD and FIONBIO. FIONREAD returns in argp the number of bytes that are available to read. FIONBIO sets the socket I/O mode to nonblocking if argp points to 1, and sets the socket I/O mode to blocking if argp points to 0.
Return Value
If successful, ioctl() returns 0. If it is unsuccessful, it returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EBADF
The s value is not a valid socket descriptor.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL
The request or argp parameter is not valid.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTINSTLD
The requested protocol is not installed.
Example A-30 illustrates the listen() syntax.
listen() Syntax
Description
The listen() function checks for connections on a socket.
To accept connections, a socket() call must first create a socket with the descriptor s. A listen() call must then indicate that incoming connections are acceptable and must create a queue limit for incoming connections. An accept() call then accepts the connections.
The listen() call applies only to sockets of type SOCK_STREAM.
The backlog parameter defines the maximum length for the queue of pending connections. If a connection request arrives when the queue is full, the client receives an error with an indication of ECONNREFUSED. The backlog parameter can have any value from 1 through 5.
Return Value
If successful, listen() returns 0. If unsuccessful, listen() returns -1 and stores a code for the encountered error in errno. DOS applications can check the global variable errno to determine the error value. Windows applications can use the GetErrno() function to determine the error value in the errno variable in the DLL.
Errors
The errno variable can take the following values:
EBADF
The s value is not a valid socket descriptor.
EINTR (DOS library only)
The current operation was interrupted.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket
function calls.
ENOTINSTLD
The requested protocol is not installed.
EOPNOTSUPP
The socket is not of a type that supports the listen() function.
Example A-31 illustrates the loaded() syntax.
loaded() Syntax
Description
The loaded() function verifies that the required TCP/IP for DOS TCP/IP transport device driver (TCPIP.EXE) has been successfully installed and is operational. Applications using transport services via the socket interface should call the loaded() function to check the drivers.
Return Values
The loaded() function returns 1 if the transport device driver is working; otherwise, the function returns 0. If the function returns 0, the application program should not attempt to use socket library function calls.
Example A-32 illustrates the raddr() syntax.
raddr() Syntax
Description
The raddr() function takes the 32-bit Internet address in network byte order in iaddr and returns the corresponding hostname in name. The function first tries to resolve the address into a name by querying the name servers on the network. If the name servers fail to respond, it searches the HOSTS database file (or series of HOSTS files as defined by the PATH TCP_CFG setting under Protocol TCPIP in the NET.CFG file).
The function puts the canonical name, which is the string returned from the query to the name server or the first name in the host's entry in the HOSTS file, into the storage area pointed to by name. The name parameter is handled slightly differently in the DOS and Windows libraries:
DOS Library Return Value
If the function receives a response from a name server or finds the address in the HOSTS file, it returns a pointer to a string containing the canonical name. Otherwise, it returns -1. The application can check the global variables dns_errno and h_errno for further information on the error condition.
Windows Library Return Value
If the function receives a response from a name server or finds the address in the HOSTS file, it returns a global HANDLE for a string containing the canonical name. Otherwise, it returns NULL. The application can then use the GetHErrno() and GetDNSErrno() functions to determine the error value in the h_errno and dns_errno variables in the DLL.
Errors
The dns_errno variable reflects errors that arose when using name servers to resolve names and addresses. It can take the following values:
FILE_NOT_FOUND
The RESOLV.CFG file does not exist in any directory in the PATH TCP_CFG setting under Protocol TCPIP in the NET.CFG file. This error does not indicate a corrupted file.
NS_NOT_RESPONDING
The network name server(s) did not respond to a message. This could mean either that the name server(s) could not resolve the name or address, or that the name server(s) are not functioning. If the network has more than one name server and the name servers are listed in the RESOLV.CFG file, the second condition rarely occurs.
The h_errno variable reflects errors that arose when using the HOSTS file to resolve names and addresses. It can take the following values:
HOST_NOT_FOUND
No entry was found corresponding to the name or address in any HOSTS file in the search path.
NO_RECOVERY
No HOSTS file could be accessed.
TRY_AGAIN
The name or address could not be resolved at the time of the request because of internal factors. Another attempt to resolve the name may be successful.
Example A-33 illustrates the syntax for the readv() and readv_anr() functions.
readv() and readv_anr() Syntax
Description
The readv() and readv_anr() functions attempt to put network data into one or more data buffers, as specified by iov and iovent, with the socket specified by the s descriptor. The iov parameter points to an array iovcnt elements long, consisting of iovec structures. These functions scatter the input data to the buffers specified by the members of the iov array. The number of iov array members is specified by iovent (iov[0],iov[l],..., iov[iovent-l]).
The iovec structure is defined in SOCKET.H as illustrated in Example A-34.
iovec Structure
The SOCKET.H include file has the following type definition for the DOS library:
For the Windows library, the type definition is as follows:
Each iovec entry specifies the base address and length of an area in memory where data should be placed. These calls always fill an area completely before proceeding to the next.
The readv_anr() function differs from readv() in that it initiates a read of network data into one to eight buffers (as specified by the iov and iovent parameters), then immediately returns control to the caller. When the read operation terminates, either successfully or unsuccessfully, the socket library updates the result parameter, and calls the user-supplied function post_routine().
The post_routine parameter is the address of a user-supplied function that is called upon completion of the readv_anr() function. The readv_anr() function passes two parameters, usercb and error_code, to the post_routine() function. The usercb parameter is a user-supplied value that can be used to distinguish among multiple outstanding requests to the same post_routine() function. The error_code parameter contains a value from SOCKET.H indicating the type of error if there was an error. If there was no error, it has the value EOK (0).
Return Value
If successful, the readv() function returns the number of characters actually read and placed in the buffer. If the returned value is 0, the connection has been closed and you should issue a soclose() function call on the socket. Otherwise, the readv() function returns -1 and stores a code for the encountered error in the errno variable (a global variable in the DOS library; accessible using the GetErrno() function in the Windows library).
A successful readv_anr() call returns 0 to the caller in immediate_result, indicating that the operation is in progress and the caller's post_routine will be called upon completion. The result parameter is a pointer to an integer that receives the result. Upon completion, the result field contains a positive number indicating the number of characters actually read, or a negative value if the operation failed. A return of 0 indicates that the remote peer has closed the connection and you should issue a soclose() function call on the socket. The function stores a code for the encountered error in the errno variable and in the error_code variable, which it passes to the caller's post_routine() function.
An unsuccessful readv_anr() call returns a negative value in immediate_result and stores a code for the encountered error in the errno variable (a global variable in the DOS library; accessible using the GetErrno() function in the Windows library).
Errors
The readv() or readv_anr() calls fail if one or more of the following conditions exist:
EASYNCNOTSUPP
The requested asynchronous operation cannot be performed. This error occurs when DOS applications run under standard mode in Windows or under DESQview and request asynchronous services.
EBADF
The s value is not a valid socket descriptor open for reading.
EINTR (DOS library only)
The current operation was interrupted.
EINVAL
The iovent parameter was less than or equal to 0, or greater than 8.
The sum of the iov_len values in the iov array overflowed a 16-bit integer.
ENO_RCB
The socket library has run out of internal resources because there are too many outstanding socket function calls.
ENOTCONN
The socket is not connected.
ENOTINSTLD
The requested protocol is not installed.
Example A-35 illustrates the recv() and recv_anr() syntax.
recv() and recv_anr() Syntax
Description
The recv() and recvnr() functions receive messages from a socket.
The recv() and recv_anr() functions are used only on connected sockets. The recvfrom() and recvmsg() functions and their asynchronous counterparts can be used to receive data on a socket whether it is connected or not.
The recv() function returns the length of the message in cc. If a message is too long to fit in the supplied buffer, excess bytes are discarded if the socket is of type SOCK_DGRAM. SOCK STREAM sockets never discard data.
If no messages are available at the socket, the recv() function waits for a message to arrive, unless the socket is nonblocking, in which case the function returns a value of -1 in cc, and sets the global variable errno to EWOULDBLOCK (errno is directly accessible to DOS applications; Windows applications can use GetErrno() to determine which error occurred). Refer to ioctl() for setting the socket to be nonblocking. The select() function can be used to determine when more data arrives.
The recv_anr() function differs from recv() in that it initiates a read of network data into the buffer specified by the buf and len parameters, then immediately returns control to the caller. When the read operation terminates, either successfully or unsuccessfully, the socket library notifies the caller by updating the field pointed to by the result argument, and by calling the user-supplied function post_routine().
The post_routine parameter is the address of a user-supplied function that is called upon completion of the recv_anr() function. The recv_anr() function passes two parameters, usercb and error_code, to the post_routine() function. The usercb parameter is a user-supplied value that can be used to distinguish among multiple outstanding requests to the same post_routine() function. The error_code parameter contains a value from SOCKET.H indicating the type of error if there was an error. If there was no error, it has the value EOK (0).
The length of the message is returned in result. If a message is too long to fit in the supplied buffer, excess bytes are discarded if the type of socket the message is received from is SOCK DGRAM. Stream sockets never discard data.
If no messages are available at the socket, the recv_anr() function waits for a message to arrive. The select_anr() function can be used to determine when more data arrives.