# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# Chapter 4
Sockets API Reference

This chapter describes the Sockets API functions that are listed in Table 4-1.

Table 4-1 Sockets API Functions
Function | Description
--- | ---
`accept()` | Accepts a connection on a passive socket.
`bind()` | Binds a name to a socket.
`close()` | Closes a connection and deletes a socket descriptor.
`connect()` | Initiates a connection on a socket.
`decc$get_sdc()` | Returns the socket device's OpenVMS I/O channel associated with a socket descriptor (for use with Compaq C).
`gethostbyaddr()` | Searches the hosts database for a host record with a given IPv4 address.
`gethostbyname()` | Searches the hosts database for a host record with a given name or alias.
`gethostname()` | Returns the fully qualified name of the local host.
`getnameinfo()` | Gets a node name and service name for an address and port number.
`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.
`getpeername()` | Returns the name of the connected peer.
`getprotobyname()` | Searches the protocols database until a matching protocol name is found or until end of file is encountered.
`getprotobynumber()` | Searches the protocols database until a matching protocol number is found or until end of file is encountered.
`getprotoent()` | Reads the next line in the protocols database.
`getservbyname()` | Gets information on the named service from the network services database.
`getservbyport()` | Gets information on the named port from the network services database.
`getsockname()` | Returns the name associated with a socket.
`getsockopt()` | Returns the options set on a socket.
`htonl()` | Converts longwords from host byte order to network byte order.
`htons()` | Converts short integers from host byte order to network 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()` | Given a network address and a local address on that network, returns an internet address.
`inet_netof()` | Returns the internet network address portion of an internet address.
`inet_network()` | Converts a null-terminated text string representing an internet address into a network address in local host format.
`inet_ntoa()` | Converts an internet address into an ASCII (null-terminated) string.
`ioctl()` | Controls devices. Used for setting sockets for nonblocking I/O.
`listen()` | Sets the maximum limit of outstanding connection requests for a TCP socket.
`ntohl()` | Converts longwords from network byte order into host byte order.
`ntohs()` | Converts short integers from network byte order into host byte order.
`read()` | Reads bytes from a file or socket and places them into a user-defined buffer.
`recv()` | Receives bytes from a connected socket and places them into a user-defined buffer.
`recvfrom()` | Receives bytes for a socket from any source.
`recvmsg()` | Receives bytes on a socket and places them into scattered buffers.
`select()` | Allows the polling or checking of a group of sockets for I/O activity.
`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.
`setsockopt()` | Sets options on a socket.
`shutdown()` | Shuts down all or part of a bidirectional connection on a socket.
`socket()` | Creates an endpoint for communication by returning a socket descriptor.
`write()` | Writes bytes from a buffer to a file or socket.

# 4.1 Sockets API

This section describes functions that comprise the Sockets API and that are supported by TCP/IP Services.

# accept()

> Accepts a connection on a passive socket.

> The $QIO equivalent is the IO$_ACCESS function with the IO$M_ACCEPT function modifier.

## Format

> #include <types.h>

> #include <socket.h>

> int accept ( int s, struct sockaddr *addr, int *addrlen );

## Arguments

> ### s

> A socket descriptor returned by `socket()` , subsequently bound to an address with `bind()` , which is listening for connections after a `listen()` .

> ### addr

> A result parameter filled in with the address of the connecting entity, as known to the Communications layer. The exact format of the structure to which the address parameter points is determined by the domain in which the communication is occurring. This version of Compaq C supports only the internet domain (AF_INET).

> ### addrlen

> A value/result argument. It should initially contain the size of the structure pointed to by addr. On return it will contain the actual length, in bytes, of the `sockaddr` structure that has been filled in by the Communications layer. See Section 3.2.7 for a description of the `sockaddr` structure.

## Description

> This function completes the first connection on the queue of pending connections, creates a new socket with the same properties as s, and allocates and returns a new descriptor for the socket. If no pending connections are present on the queue and the socket is not marked as nonblocking, `accept()` blocks the caller until a connection request is present. If the socket is marked nonblocking by using a `setsockopt()` call and no pending connections are present on the queue, `accept()` returns an error. You cannot use the accepted socket to accept subsequent connections. The original socket s remains open (listening) for other connection requests. This call is used with connection-based socket types ( `SOCK_STREAM` ).

> Related Functions

> See also `bind()` , `connect()` , `listen()` , `select()` , and `socket()` .

## Return Values

> x | A nonnegative integer that is a descriptor for the accepted socket.
> -1 | Error; `errno` is set to indicate the error.

## Errors

> EBADF | The socket descriptor is invalid.
> ECONNABORTED | A connection has been aborted.
> EFAULT | The addr argument is not in a writable part of the user address space.
> EINTR | The `accept()` function was interrupted by a signal before a valid connection arrived.
> EINVAL | The socket is not accepting connections.
> EMFILE | There are too many open file descriptors.
> ENFILE | The maximum number of file descriptors in the system is already open.
> ENETDOWN | TCP/IP Services was not started.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOMEM | The system was unable to allocate kernel memory.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The reference socket is not of type `SOCK_STREAM` .
> EPROTO | A protocol error occurred.
> EWOULDBLOCK | The socket is marked nonblocking, and no connections are present to be accepted.

# bind()

> Binds a name to a socket.

> The $QIO equivalent is the IO$_SETMODE function with the p3 argument.

## Format

> #include <types.h>

> #include <socket.h>

> int bind ( int s, struct sockaddr *name, int namelen );

## Arguments

> ### s

> A socket descriptor created with the `socket() function` .

> ### name

> Address of a structure used to assign a name to the socket in the format specific to the family (AF_INET) socket address. See Section 3.2.7 for a description of the `sockaddr` structure.

> ### namelen

> The size, in bytes, of the structure pointed to by name.

## Description

> This function assigns a port number and IP address to an unnamed socket. When a socket is created with the `socket()` function, it exists in a name space (address family) but has no name assigned. The `bind()` function requests that a name be assigned to the socket.

> Related Functions

> See also `connect()` , `getsockname()` , `listen()` , and `socket()` .

## Return Values

> 0 | Successful completion.
> -1 | Error; `errno` is set to indicate the error.

## Errors

> EACCESS | The requested address is protected, and the current user has inadequate permission to access it.
> EADDRINUSE | The specified internet address and ports are already in use.
> EADDRNOTAVAIL | The specified address is not available from the local machine.
> EAFNOSUPPORT | The specified address is invalid for the address family of the specified socket.
> EBADF | The socket descriptor is invalid.
> EDESTADDRREQ | The address argument is a null pointer.
> EFAULT | The name argument is not a valid part of the user address space.
> EINVAL | The socket is already bound to an address and the protocol does not support binding to a new address, the socket has been shut down, or the length or the namelen argument is invalid for the address family.
> EISCONN | The socket is already connected.
> EISDIR | The address argument is a null pointer.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The socket type of the specified socket does not support binding to an address.

# close()

> Closes a connection and deletes a socket descriptor.

> The $QIO equivalent is the $DASSGN system service.

## Format

> #include <unixio.h>

> int close ( s );

## Argument

> ### s

> A socket descriptor.

## Description

> This function deletes a descriptor from the per-process object (Compaq C structure) reference table. Associated TCP connections close first.

> If a call to the `connect()` function fails for a connection mode socket, applications should use `close()` to deallocate the socket and descriptor.

> Related Functions

> See also `accept()` , `socket()` , and `write()` .

## Return Values

> 0 | Successful completion.
> -1 | Error; `errno` is set to indicate the error.

## Errors

> EBADF | The socket descriptor is invalid.
> EINTR | The `close()` function was interrupted by a signal that was caught.

# connect()

> Initiates a connection on a socket.

> The $QIO equivalent is the IO$_ACCESS function.

## Format

> #include <types.h>

> #include <socket.h>

> int connect ( int s, struct sockaddr *name, int namelen );

## Arguments

> ### s

> A socket descriptor created with `socket()` .

> ### name

> The address of a structure that specifies the name of the remote socket in the format specific to the address family (AF_INET).

> ### namelen

> The size, in bytes, of the structure pointed to by name.

## Description

> If s is a socket descriptor of type `SOCK_DGRAM` , then this call permanently specifies the peer where the data is sent. If s is of type `SOCK_STREAM` , then this call attempts to make a connection to the specified socket.

> Each communications space interprets the name argument. This argument specifies the socket that is connected to the socket specified in s.

> If the `connect()` function fails for a connection-mode socket, applications should use the `close()` function to deallocate the socket and descriptor. If attempting to reinitiate the connection, applications should create a new socket.

> Related Functions

> See also `accept()` , `select()` , `socket()` , `getsockname()` , and `shutdown()` .

## Return Values

> 0 | Successful completion.
> -1 | Error; `errno` is set to indicate the error.

## Errors

> EADDRINUSE | Configuration problem. There are insufficient ports available for the attempted connection. The `ipport_userreserved` variable of the inet subsystem should be increased.
> EADDRNOTAVAIL | The specified address is not available from the local machine.
> EAFNOSUPPORT | The addresses in the specified address family cannot be used with this socket.
> EALREADY | A connection request is already in progress for the specified socket.
> EBADF | The socket descriptor is invalid.
> ECONNREFUSED | The attempt to connect was rejected.
> EFAULT | The name argument is not a valid part of the user address space.
> EHOSTUNREACH | The specified host is not reachable.
> EINPROGRESS | O_NONBLOCK is set for the file descriptor for the socket, and the connection cannot be immediately established; the connection will be established asynchronously.
> EINTR | The `connect()` function was interrupted by a signal while waiting for the connection to be established. Once established, the connection may continue asynchronously.
> EINVAL | The value of the namelen argument is invalid for the specified address family, or the `sa_family` field in the socket address structure is invalid for the protocol.
> EISCONN | The socket is already connected.
> ELOOP | Too many symbolic links were encountered in translating the file specification in the address.
> ENETDOWN | The local network connection is not operational.
> ENETUNREACH | No route to the network or host is present.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The socket is listening and cannot be connected.
> EPROTOTYPE | The specified address has a different type than the socket bound to the specified peer address.
> ETIMEDOUT | The connection request timed out without establishing a connection.
> EWOULDBLOCK | The socket is nonblocking, and the connection cannot be completed immediately. It is possible to use the `select()` function to select the socket for writing.

Previous | Next | Contents | Index