Converts short integers from network to host byte order.

Format

#include <in.h>

unsigned short int ntohs (unsigned short int netshort);

Argument

netshort

A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on VAX systems.

Description

This routine converts 16-bit unsigned integers from network byte order to host byte order.

The network byte order is the format in which data bytes are supposed to be transmitted through a network. All hosts on a network must send data in network byte order. Not all hosts have an internal data representation format that is identical to the network byte order. The host byte order is the format in which bytes are ordered internally on a specific host.

The host byte order on VAX systems differs from the network order.

This routine is most often used with Internet addresses and ports as returned by gethostent and getservent , and when manipulating values in the structures. Network byte order places the byte with the most significant bits at lower addresses; VAX systems place the most significant bits at the highest address.

Return Value

x	A short integer in host (VAX) byte order.

Reads bytes from a socket or file and places them in a buffer.

Format

#include <unixio.h>

int read (int d, void *buffer, int nbytes);

Arguments

d

A descriptor that must refer to a socket or file currently opened for reading.

buffer

The address of contiguous storage in which the input data is placed.

nbytes

The maximum number of bytes involved in the read operation.

Description

If the end-of-file is not reached, the read routine returns nbytes. If the end-of-file occurs during the read routine, it returns the number of bytes read.

Upon successful completion, read returns the number of bytes actually read and placed in the buffer.

See also socket in this section.

Return Values

x	The number of bytes read and placed in the file.
--1	Indicates an error; errno is set to one of the following: EBADF -- The socket descriptor is invalid. EFAULT -- The buffer points outside the allocated address space. EINVAL -- The nbytes argument is negative. EWOULDBLOCK -- The nbio socket option (nonblocking) flag is set for the socket or file descriptor and the process would be delayed in the read operation.

Receives bytes from a connected socket and places them into a buffer.

Format

#include <socket.h>

int recv (int s, char *buf, int len, int flags);

(_DECC_V4_SOURCE) ssize_t recv (int s, void *buf, size_t len, int flags);

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor that was created as the result of a call to accept or connect .

buf

A pointer to a buffer into which received data will be placed.

len

The size of the buffer pointed to by buf.

flags

A bit mask that may contain one or more of msg_oob and msg_peek . It is built by ORing the appropriate values together.

The msg_oob flag allows out-of-band data to be received. If out-of-band data is available, it will be read before any other data that is available. If no out-of-band data is available, the msg_oob flag is ignored. Out-of-band data can be sent using send , sendmsg , and sendto .

The msg_peek flag allows you to peek at the data that is next in line to be received without removing it from the system's buffers.

Description

This routine receives data from a connected socket. To receive data on an unconnected socket, use the recvfrom or recvmsg routines. The received data is placed in the buffer buf.

Data is sent by the socket's peer using the send , sendmsg , or sendto routines.

You may use the select routine to determine when more data arrives.

If no data is available at the socket, the receive call waits for data to arrive, unless the socket is nonblocking in which case a --1 is returned with the external variable errno set to ewouldblock .

See also read , send , sendmsg , sendto , and socket in this section.

Return Values

x	The number of bytes received and placed in buf.
0	Indicates that a connection is broken or reset by its peer.
--1	Indicates an error; errno is set to one of the following: EBADF -- The socket descriptor is invalid. ENOTSOCK -- The descriptor references a file, not a socket. EPIPE -- An attempt was made to write to a socket that is not open for reading by any process. EWOULDBLOCK -- The nbio socket option (nonblocking) flag is set for the socket or file descriptor and the process would be delayed in the read operation. EFAULT -- The data was specified to be received into a non-existent or protected part of the process address space.

Receives bytes from a socket from any source.

Format

#include <socket.h>

int recvfrom (int s, char *buf, int len, int flags, struct sockaddr *from, int *fromlen)

; (_DECC_V4_SOURCE) ssize_t recvfrom (int s, void *buf, size_t len, int flags, struct sockaddr *from, size_t *fromlen)

; (NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor that has been created with socket and bound to a name using bind or as a result of accept .

buf

A pointer to a buffer into which received data will be placed.

len

The size of the buffer pointed to by buf.

flags

A bit mask that may contain one or more of msg_oob and msg_peek . It is built by ORing the appropriate values together.

The msg_oob flag allows out-of-band data to be received. If out-of-band data is available, it will be read before any other data that is available. If no out-of-band data is available, the msg_oob flag is ignored. Out-of-band data can be sent using send , sendmsg , and sendto .

The msg_peek flag allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

from

If from is nonzero, from is a buffer into which recvfrom places the address (structure) of the socket from which the data is received. If from was 0, the address will not be returned.

fromlen

Points to an integer containing the size of the buffer pointed to by from. On return, the integer is modified to contain the actual length of the socket address structure returned.

Description

This routine allows a named, unconnected socket to receive data. The data is placed in the buffer pointed to by buf, and the address of the sender of the data is placed in the buffer pointed to by from if from is non-NULL. The structure that from points to is assumed to be as large as the sockaddr structure. See <socket.h> for a description of the sockaddr structure.

To receive bytes from any source, the sockets need not be connected to another socket.

You may use the select routine to determine if data is available.

If no data is available at the socket, the recv call waits for data to arrive, unless the socket is nonblocking, in which case a --1 is returned with the external variable errno set to ewouldblock .

See also read , send , sendmsg , sendto , and socket in this section.

Return Values

x

The number of bytes of data received and placed in buf.

--1

Indicates an error; errno is set to one of the following values: EBADF -- The socket descriptor is invalid. ENOTSOCK -- The socket descriptor references a file, not a socket. EPIPE -- An attempt was made to write to a socket that is not open for reading by any process. EWOULDBLOCK -- The nbio (nonblocking) flag is set for the socket descriptor and the process would be delayed in the write operation. EFAULT -- The data was specified to be received into a non-existent or protected part of the process address space.

Receives bytes on a socket and places them into scattered buffers..

Format

#include <socket.h>

int recvmsg (int s, struct msghdr msg[], int flags);

Arguments

s

A socket descriptor that has been created with socket .

msg

A msghdr structure. See <socket.h> for a description of the msghdr structure.

flags

A bit mask that may contain one or more of msg_oob and msg_peek . It is built by ORing the appropriate values together.

The msg_oob flag allows out-of-band data to be received. If out-of-band data is availiable, it will be read before any normal data that is available. If no out-of-band data is available, the msg_oob flag is ignored. Out-of-band data can be sent using send , sendmsg , and sendto .

The msg_peek flag allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

Description

This routine may be used with any socket, whether it is in a connected state or not. It receives data sent by a call to sendmsg , send , or sendto . The message is scattered into several user buffers if such buffers are specified.

To receive data, the socket need not be connected to another socket.

When the iovec[iovcnt] array specifies more than one buffer, the input data is scattered into iovcnt buffers as specified by the members of the iovec array:

iov[0], iov[1], ..., iov[iovcnt]

When a message is received, it is split among the buffers by filling the first buffer in the list, then the second, and so on, until either all of the buffers are full or there is no more data to be placed in the buffers.

When a message is sent, the first buffer is copied to a system buffer and then the second buffer is copied, followed by the third buffer and so on, until all the buffers are copied. After the data is copied, the protocol will send the data to the remote host at the appropriate time, depending upon the protocol.

You may use the select routine to determine when more data arrives.

See also read , send , and socket in this section.

Return Values

x

The number of bytes returned in the msg_iov buffers.

--1

Indicates an error; errno is set to one of the following values: EBADF -- The socket descriptor is invalid. ENOTSOCK -- The socket descriptor references a file, not a socket. EPIPE -- An attempt was made to write to a socket that is not open for reading by any process. EWOULDBLOCK -- The nbio (nonblocking) flag is set for the socket descriptor and the process would be delayed in the write operation. EINTR -- The receive was interrupted by delivery of a signal before any data was available for the receive. EFAULT -- The data was specified to be received into a non-existent or protected part of the process address space.

Allows the user to poll or check a group of sockets for I/O activity. It can check what sockets are ready to be read or written, or what sockets have a pending exception.

As of OpenVMS Version 7.0, this routine can operate on any number of sockets up to the limit of open files supported by the Compaq C RTL (65535 on OpenVMS Alpha; 2047 on OpenVMS VAX). However, for select to use more than 32 sockets, the TCP/IP Services for OpenVMS used with the Compaq C RTL must offer the same support.

Format

#include <socket.h>

int select (int nfds, int *readfds, int *writefds, int *execptfds, struct timeval *timeout);

(_DECC_V4_SOURCE) int select (int nfds, fd_set *readfds, fd_set *writefds, fd_set *execptfds, struct timeval *timeout);

(NOT _DECC_V4_SOURCE)

Arguments

nfds

The highest numbered socket descriptor to search for. That is, the highest numbered bit +1 in readfds, writefds, and exceptfds that should be examined. Descriptor s is represented by 1<< s (1 shifted to the left s number of times).

readfds

A pointer to an array of bits, organized as integers (each integer describing 32 descriptors), that should be examined for read readiness. If bit n of the longword is set, socket descriptor n will be checked to see if it is ready to be read. All bits set in the bit mask must correspond to the file descriptors of sockets. The select routine cannot be used on normal files.

On return, the array of bits to which readfds points contains a bit mask of the sockets that are ready for reading. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

writefds

A pointer to a longword bit mask of the socket descriptors that should be examined for write readiness. If bit n of the longword is set, socket descriptor n will be checked to see if it is ready to be written to. All bits set in the bit mask must correspond to socket descriptors.

On return, the array of bits that writefds points to contains a bit mask of the sockets that are ready for writing. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

exceptfds

A pointer to a longword bit mask of the socket descriptors that should be examined for exceptions. If bit n of the longword is set, socket descriptor n will be checked to see if it has any pending exceptions. All bits set in the bit mask must correspond to the file descriptors of sockets.

On return, the array of bits pointer exceptfds contains a bit mask of the sockets that have exceptions pending. Only bits that are set on entry to select will be set on exit.

If this pointer is NULL, select ignores the array.

timeout

The length of time that select should examine the sockets before returning. If one of the sockets specified in the readfds, writefds, and exceptfds bit masks is ready for I/O, select will return before the timeout period has expired.

The timeout structure points to a timeval structure. See <socket.h> for a description of the timeval structure.

Description

This routine determines the I/O status of the sockets specified in the various mask arguments. It returns either when a socket is ready to be read or written, or when the timeout period expires. If timeout is a nonzero integer, it specifies a maximum interval to wait for the selection to complete.

If the timeout argument is NULL, select will block indefinitely. In order to effect a poll, timeout should be non-NULL, and should point to a zero-valued structure.

If a process is blocked on a select while waiting for input from a socket and the sending process closes the socket, the select notes this as an event and will unblock the process. The descriptors are always modified on return if select returns because of the timeout.

Note When the socket option SO_OOBINLINE is set on the device_socket, a select on both read and exception events returns the socket mask set on both the read and exception mask. Otherwise, only the exception mask is set.

See also accept , connect , read , recv , recvfrom , recvmsg , send , sendmsg , sendto , and write in this section.

Return Values

n	The number of sockets that were ready for I/O or that had pending exceptions. This value matches the number of returned bits that are set in all output masks.
0	Indicates that select timed out before any socket became ready for I/O.
--1	Indicates an error; errno is set to one of the following values: EBADF -- One of the bit masks specified an invalid descriptor. EINVAL -- The specified time limit is unacceptable. One of its components is negative or too large.

Sends bytes though a socket to its connected peer.

Format

#include <socket.h>

int send (int s, char *msg, int len, int flags);

(_DECC_V4_SOURCE) ssize_t send (int s, const void *msg, size_t len, int flags);

(NOT _DECC_V4_SOURCE)

Arguments

s

A socket descriptor that was created with socket , and connected to another socket using accept or connect .

msg

A pointer to a buffer containing the data to be sent.

len

The length, in bytes, of the data pointed to by msg.

flags

May be either 0 or msg_oob . If it is equal to msg_oob , the data will be sent out-of-band. This means that the data can be received before other pending data on the receiving socket if the receiver also specifies a msg_oob in the flag parameter of the call.

Description

This routine may only be used on connected sockets. To send data on an unconnected socket, use the sendmsg or sendto routines. The send routine passes data along to its connected peer, which may receive the data by using recv .

If there is no space available to buffer the data being sent on the receiving end of the connection, send will normally block until buffer space becomes available. If the socket is defined as nonblocking, however, send will fail with an errno indication of ewouldblock . If the message is too large to be sent in one piece and the socket type requires that messages be sent atomically (using SOCK_DGRAM), send will fail with an errno indication of emsgsize .

No indication of failure to deliver is implicit in a send . All errors (except ewouldblock ) are detected locally. You may use the select routine to determine when it is possible to send more data.

See also read , recv , recvmsg , recvfrom , getsocketopt , and socket in this appendix.

Return Values

n

The number of bytes sent. This value will normally equal len.

--1

Indicates an error; errno is set to one of the following: EBADF -- The socket descriptor is invalid. ENOTSOCK -- The descriptor references a file, not a socket. EFAULT -- An invalid user space address was specified for a parameter. EMSGSIZE --The socket requires that messages be sent atomically, and the size of the message to be sent made this impossible. EWOULDBLOCK -- Blocks if the system does not have enough space for buffering the user data.

privacy and legal statement