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


Previous Contents Index


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

[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

[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().

If a connection request arrives with the queue full (more than backlog connection requests pending), the request is ignored so that TCP retries can succeed. If the backlog has not cleared by the time TCP times out, the connect() call fails with an errno indication of ETIMEDOUT.

See also accept(), connect(), and socket().


Return Values

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

Errors

[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The socket descriptor references a file, not a socket.
[EOPNOTSUPP] The socket is not of a type that supports the operation listen().

read()

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

The $QIO equivalent is the IO$_READVBLK function.


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 a user-provided buffer in which the input data is placed.

nbytes

The maximum number of bytes allowed 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().


Return Values

x The number of bytes read and placed in the buffer.
0 Peer has closed the connection.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The 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.

recv()

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

The $QIO equivalent is the IO$_READVBLK function.


Format

#include <types.h>

#include <socket.h>

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


Arguments

s

A socket descriptor created as the result of a call to accept() or connect().

buf

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

len

The size of the buffer pointed to by buf.

flags

A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data.
  If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored.
  Use the send(), sendmsg(), and sendto() to send out-of-band data.
MSG_PEEK Allows you to peek at the data next in line to be received without actually removing it from the system's buffers.

If you include the TCPIP$INETDEF.H definition file, use the flags listed in the following table:
Flag Description
TCPIP$C_MSG_NBIO Does not block the I/O operation if the receive queue is full. Similar to using the $QIO IO$M_NOWAIT function.
TCPIP$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function.
TCPIP$C_MSG_BLOCKALL Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function.


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.

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().


Return Values

x The number of bytes received and placed in buf.
0 Peer has closed.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a socket.
[EPIPE] You tried 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 is delayed during the write operation.
[EFAULT] The data was specified to be received into a nonexistent or protected part of the process address space.

recvfrom()

Receives bytes for a socket from any source.

Format

#include <types.h>

#include <socket.h>

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

;

Arguments

s

A socket descriptor 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 is placed.

len

The size of the buffer pointed to by buf.

flags

A bit mask that can contain one or more MSG_OOB and MSG_PEEK flag. It is built by ORing the appropriate values together, as follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data. If out-of-band data is available, it is read first.
  If no out-of-band data is available, the MSG_OOB flag is ignored. To send out-of-band data, use the send(), sendmsg(), and sendto().
MSG_PEEK Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

If you include the TCPIP$INETDEF.H definition file, use the flags listed in the following table:
Flag Description
TCPIP$C_MSG_NBIO Does not block the I/O operation if the receive queue is full. Similar to using the $QIO IO$M_NOWAIT function.
TCPIP$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE modifier.
TCPIP$C_MSG_BLOCKALL Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using the $QIO IO$M_LOCKBUF function.

from

A buffer that the recvfrom routine uses to place the address of the socket from which the data is received.

If from is nonzero, the address is returned. If from is 0, the address is not 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 Section 5.8.7 for a description of sockaddr structure.

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

You can use the select() routine to determine if data is available.

If no data is available at the socket, the recvfrom() 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().


Return Values

x The number of bytes of data received and placed in buf.
0 Successful completion.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a socket.
[EPIPE] You tried 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 delayed during the write operation.
[EFAULT] The data is specified to be received into a non-existent or protected part of the process address space.

recvmsg()

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

Format

#include <types.h>

#include <socket.h>

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

int recvmsg (int s, struct omsghdr msg[], int flags); (BSD Version 4.3)


Arguments

s

A socket descriptor created with socket().

msg

See Section 5.8.5 for a description of the msghdr structure for BSD Versions 4.3 and 4.4.

flags

A bit mask that can contain one or more MSG_OOB and MSG_PEEK flags. It is built by ORing the appropriate values together, as follows:
Flag Description
MSG_OOB Allows you to receive out-of-band data.
  If out-of-band data is available, it is read first. If no out-of-band data is available, the MSG_OOB flag is ignored. Use send(), sendmsg(), and sendto() routines to send out-of-band data.
MSG_PEEK Allows you to peek at the data that is next in line to be received without actually removing it from the system's buffers.

If you include the TCPIP$INETDEF.H definition file, you can use the flags listed in the following table:
Flag Description
TCPIP$C_MSG_NBIO Does not block the I/O operation if the receive queue is full. Similar to using the $QIO IO$M_NOWAIT function.
TCPIP$C_MSG_PURGE Flushes data from the queue. Similar to using the $QIO IO$M_PURGE function.
TCPIP$C_MSG_BLOCKALL Blocks the completion of the operation until the buffer is filled completely or until the connection is closed. Similar to using to the $QIO IO$M_LOCKBUF modifier.


Description

You can use this routine 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.

You can use the select() routine to determine when more data arrives.

See also read(), send(), and socket().


Return Values

x The number of bytes returned in the msg_iov buffers.
0 Successful completion.
--1 Error; errno is set to indicate the error.

Errors

[EBADF] The socket descriptor is invalid.
[ENOTSOCK] The descriptor references a file, not a socket.
[EPIPE] You tried to read 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 is delayed during the read operation.
[EINTR] The receive is interrupted by delivery of a signal before any data is available for the receive.
[EFAULT] The data is specified to be received into a non-existent or protected part of the process address space.


Previous Next Contents Index