# DIGITAL TCP/IP Services for OpenVMS
System Services and C Socket Programming

Previous | Contents

The members of the sockaddr structure are:

1. sa_family is the address family or domain in which the socket was created.
2. sa_data is the data string of up to 14 bytes of direct address.

## 5.8.8 sockaddr_in Structure

The sockaddr_in structure, defined in the <in.h> header file, specifies an internet address family.

The sockaddr_in structure is defined as follows:

    struct sockaddr_in {
            short   sin_family;(1)       /* address family */
            u_short sin_port;(2)         /* port number */
            struct  in_addr sin_addr;(3) /* internet address */
            char    sin_zero[8];(4)      /* 8-byte field of all zeroes */
    };

The members of the sockaddr_in structure are:

1. sin_family is the address family (internet domain (AF_INET)).
2. sin_port is the port number in network order.
3. sin_addr is the internet address in network order.
4. sin_zero is an 8-byte field containing all zeros.

## 5.8.9 timeval Structure

The timeval structure, defined in the <socket.h> header file, specifies time intervals. This structure is defined as follows:

    struct timeval {
        long tv_sec;(1)
        long tv_usec;(2)
    };

The members of the timeval structure are:

1. tv_sec specifies the number of seconds to wait.
2. tv_usec specifies the number of microseconds to wait.

# 5.9 errno Values

The external variable errno has its value set whenever an error occurs during a call to any of the DEC C Run-Time Library routines. The errors are defined in errno.h. Use the errno value to obtain a more detailed description of the error. Because errno is not cleared on successful calls, you should check its value only when an error has been indicated.

Most calls to the DEC C Run-Time Library routines have one or more returned values. Any error condition is indicated by an otherwise impossible return value. This is usually --1. The individual routine descriptions specify the details.

All return codes and values from routines are of type integer unless otherwise noted. An error number is also made available in the external variable errno, which is not cleared on successful calls. The errno values can be translated to a message, similar to that found in UNIX systems, by using the perror function. The variable vaxc$errno can also be returned as an error.

Table 5-2 lists the errno values.

Table 5-2 errno Values
Value | Meaning
--- | ---
EADDRINUSE | Address already in use.
| Each address can be used only once.
EADDRNOTAVAIL | Cannot assign requested address.
| Normally, these values results from an attempt to create a socket with an address not on this machine.
EAFNOSUPPORT | Address family not supported by protocol family.
| An address incompatible with the requested protocol was used.
EALREADY | Operation already in progress.
| An operation was attempted on a nonblocking object that already had an operation in progress.
ECONNABORTED | Software caused connection abort.
| A connection abort was caused internal to your host machine.
ECONNREFUSED | Connection refused.
| No connection could be made because the target machine actively refused it. This usually results from trying to connect to a service that is inactive on the foreign host.
ECONNRESET | Connection reset by peer.
| A connection was forcibly closed by a peer. This usually results from the peer executing a shutdown() call.
EDESTADDRREQ | Destination address required.
| A required address was omitted from an operation on a socket.
EHOSTDOWN | Host is down.
| A socket operation failed because the destination host was down.
EHOSTUNREACH | No route to host.
| A socket operation was attempted to an unreachable host.
EINPROGRESS | Operation now in progress.
| An operation that takes a long time to complete, such as connect(), was attempted on a nonblocking object.
EISCONN | Socket is already connected.
| A connect() request was made on an already connected socket; or, a sendto() or sendmsg() request on a connected socket specified a destination other than the connected party.
ELOOP | Too many levels of symbolic links.
| A path name lookup involved more than eight symbolic links.
EMSGSIZE | Message too long.
| A message sent on a socket was larger than the internal message buffer.
ENAMETOOLONG | File name too long.
| A component of a path name exceeded 255 characters, or an entire path name exceeded 1023 characters.
ENETDOWN | Network is down.
| A socket operation encountered a dead network.
ENETRESET | Network dropped connection on reset.
| The host you were connected to crashed and rebooted.
ENETUNREACH | Network is unreachable.
| A socket operation was attempted to an unreachable network.
ENOBUFS | No buffer space available.
| An operation on a socket or pipe was not performed because the system lacked sufficient buffer space.
ENOPROTOOPT | Protocol not available.
| A bad option was specified in a getsockopt() or setsocketopt() call.
ENOTSOCK | Socket operation on a non-socket.
ENTOTCONN | Socket is not connected.
| Request to send or receive data was disallowed because the socket is not connected.
EOPNOTSUPP | Operation not supported.
| For example, trying to accept a connection on a datagram socket.
EPFNOSUPPORT | Protocol family not supported.
| The protocol family has not been configured into the system or no implementation for it exists.
EPROTONOSUPPORT | Protocol not supported.
| The protocol has not been configured into the system or no implementation for it exists.
EPROTOTYPE | Protocol wrong type for socket.
| A protocol was specified that does not support the semantics of the socket type requested. For example you cannot use the ARPA Internet UDP protocol with type SOCK_STREAM.
ESHUTDOWN | Cannot send after socket shutdown.
| A request to send data was disallowed because the socket had already been shut down with a previous shutdown() call.
ESOCKTNOSUPPORT | Socket type not supported.
| The support for the socket type has not been configured into the system or no implementation for it exists.
ETIMEDOUT | Connection timed out.
| A connect() request failed because the connected party did not respond properly after a period of time. (The timeout period is dependent on the communication protocol.) A connect() request or remote file operation failed because the connected party did not properly respond after a period of time that is dependent on the communication protocol.
ETOOMANYREFS | Too many references: cannot splice.
EVMSERR | OpenVMS-specific error code that is nontranslatable.

# Chapter 6
DEC C Socket Routine Reference

This chapter describes the two types of communication routines that let you write internet programs:

- Basic communication routines --- The building blocks of internet programs (listed in Table 6-1).
- Communication support routines --- For performing operations such as searching databases and reading records (listed in Table 6-2).

Chapter 5 contains information about writing internet application programs.

Table 6-1 Basic Communication Routines
Routine | 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.
listen() | Sets the maximum limit of outstanding connection requests for a TCP socket.
read() | Reads bytes from a file or socket and places them into a user-defined buffer.
readv() | Not implemented.
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.
shutdown() | Shuts down all or part of a bidirectional connection on a socket.
socket() | Creates an end point for communication by returning a socket descriptor.
write() | Writes bytes from a buffer to a file or socket.
writev() | Not implemented.

Table 6-2 Communication Support Routines
Routine | Description
--- | ---
decc$get_sdc() | Returns the socket device's OpenVMS I/O channel associated with a socket descriptor (for use with DEC C).
gethostbyaddr() | Searches the hosts database for a host record with a given 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.
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() | Reads the next record in the network database.
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 to network byte order.
htons() | Converts short integers from host 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() | 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 address into a network address in local host format.
inet_ntoa() | Converts an internet address into an ASCII (null-terminated) string.
ntohl() | Converts longwords from network byte order into host byte order.
ntohs() | Converts short integers from network byte order into host byte order.
setsockopt() | Sets options on a socket.
vaxc$get_sdc() | Returns the socket device's OpenVMS I/O channel associated with a socket descriptor (for use with VAX C).

# 6.1 Basic Communication Routines

This section describes the basic communication routines.

# 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(), and 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 DEC C supports only the internet domain (AF_INET).

> ### addrlen

> A value-result parameter. 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 structure that has been filled in by the communication layer. See Section 5.8.7 for a description of the sockaddr structure.

## DESCRIPTION

> This routine 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, currently with SOCK_STREAM.

> You can use the select() socket routine to do an accept() by selecting it for read.

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

## Return Values

> x | A non-negative integer that is a descriptor for the accepted socket.
> 0 | Successful completion.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The socket descriptor is invalid.
> [ENOTSOCK] | The socket descriptor references a file, not a socket.
> [EOPNOTSUPP] | The reference socket is not of type SOCK_STREAM.
> [EFAULT] | The addr parameter is not in a writable part of the user address space.
> [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 socket().

> ### 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 5.8.7 for a description of the sockaddr structure.

> ### namelen

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

## DESCRIPTION

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

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

## Return Values

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

## Errors

> You can set errno to the following values:
> [EBADF] | The descriptor is invalid.
> [ENOTSOCK] | The socket descriptor references a file, not a socket.
> [EADDRNOTAVAIL] | The specified address is not available from the local machine.
> [EADDRINUSE] | The specified internet address and ports are already in use.
> [EINVAL] | The socket is already bound to an address.
> [EACCESS] | The requested address is protected, and the current user has inadequate permission to access it.
> [EFAULT] | The name parameter is not a valid part of the user address space.

# 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 routine deletes a descriptor from the per-process object (DEC C structure) reference table. Associated TCP connections close first.

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

## Return Values

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

## Errors

> You can set errno to the following value:
> [EBADF] | The socket descriptor is invalid.

# 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 it is type SOCK_STREAM, then this call attempts to make a connection to the specified socket.

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

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

## Return Values

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

## Errors

> You can set errno to the following values:
> [EBADF] | The descriptor is invalid.
> [ENOTSOCK] | The socket descriptor references a file, not a socket.
> [EADDRNOTAVAIL] | The specified address is not available from the local machine.
> [EAFNOSUPPORT] | Address in the specified address family cannot be used with this socket.
> [EISCONN] | The socket is already connected.
> [ETIMEOUT] | Connection establishment timed out without establishing a connection.
> [ECONNREFUSED] | The attempt to connect is rejected explicitly when a connection request arrives with the queue full.
> [ENETUNREACH] | The network is not reachable from this host.
> [EADDRINUSE] | The specified internet address and ports are already in use.
> [EFAULT] | The name parameter is not a valid part of the user address space.
> [EWOULDBLOCK] | The socket is nonblocking and the connection cannot be completed immediately. It is possible to select() the socket while it is connecting by selecting it for writing.

# listen()

> Sets the maximum limit of outstanding connection requests for a socket that is connection oriented.

> The $QIO equivalent is the IO$_SETMODE or IO$_SETCHAR function.

## Format

> ### int listen (int s, int backlog);

## ARGUMENTS

> ### s

> A socket descriptor of type SOCK_STREAM created using socket().

> ### backlog

> The maximum number of pending connections that can be queued on the socket at any given time. The maximum is five and the smallest useful backlog limit is one.

## DESCRIPTION

> This routine creates a queue for pending connection requests on socket s with a maximum size of backlog. Connections can then be accepted with accept().

> Previous | Next | Contents