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

Previous | Contents

If no space is available to buffer the data on the receiving end of the connection, the sendmsg() routine normally blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendmsg() routine fails 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 (SOCK_DGRAM), the sendmsg() fails with an errno indication of EMSGSIZE.

If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have a system UIC, OPER, SYSPRV, or BYPASS privilege for the I/O operation to succeed.

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

See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt().

## Return Values

> n | The number of bytes sent.
> --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.
> [EFAULT] | An invalid user space address is specified for a parameter.
> [EMSGSIZE] | The socket requires that messages be sent atomically, and the size of the message to be sent makes this impossible.
> [EWOULDBLOCK] | Blocks if the system does not have enough space for buffering the user data.

# sendto()

> Sends bytes through a socket to any other socket.

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

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int sendto (int s, char *msg, int len, int flags, struct sockaddr *to, int tolen);

## ARGUMENTS

> ### s

> A socket descriptor created with socket().

> ### msg

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

> ### len

> The length of the data pointed to by msg.

> ### flags

> Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data is 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 its flag parameter of the call.

> If you include the UCX$INETDEF definition file, you can also use:

> - UCX$C_MSG_DONTROUTE --- Sends the message directly without routing.
> - UCX$C_MSG_NBIO --- Completes the I/O operation and returns an error if a condition occurs that would cause the I/O operation to be blocked. Similar to using the $QIO IO$M_NOWAIT modifier.

> ### to

> Points to the address structure of the socket to which the data is to be sent.

> ### tolen

> The length of the address structure to points to.

## DESCRIPTION

> This routine can be used on sockets to send data to named sockets. The data in the msg buffer is sent to the socket whose address is specified in the to argument, and the address of socket s is provided to the receiving socket. The receiving socket gets the data using either the read(), recv(), recvfrom(), or recvmsg() routine.

> If there is no space available to buffer the data being sent on the receiving end of the connection, the sendto() routine blocks until buffer space becomes available. If the socket is defined as nonblocking, the sendto() routine fails 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 (SOCK_DGRAM), the sendto() routine fails with an errno indication of EMSGSIZE.

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

> If the address specified is a INADDR_BROADCAST address, then the SO_BROADCAST option must be set and the process must have SYSPRV or BYPASS privilege for the I/O operation to succeed.

> See also read(), recv(), recvfrom(), recvmsg(), socket(), and getsockopt().

## Return Values

> n | The number of bytes sent. This value normally equals len.
> --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.
> [EFAULT] | An invalid user space address is specified for a parameter.
> [EMSGSIZE] | The socket requires that messages be sent atomically, and the size of the message to be sent makes this impossible.
> [EWOULDBLOCK] | Blocks if the system does not have enough space for buffering the user data.

# shutdown()

> Shuts down all or part of a bidirectional connection on a socket. This routine disallows further receives, further sends, or both.

> The $QIO equivalent is the IO$_DEACCESS function with the IO$M_SHUTDOWN function modifier.

## Format

> ### #include <socket.h>

> ### int shutdown (int s, int how);

## ARGUMENTS

> ### s

> A socket descriptor that is in a connected state as a result of a previous call to either connect() or accept().

> ### how

> How the socket is to be shut down. Use one of the following values:

> 0 (INET$C_DSC_RCV) | Disallows further calls to recv() on the socket.
> 1 (INET$C_DSC_SND) | Disallows further calls to send() on the socket.
> 2 (INET$C_DSC_ALL) | Disallows further calls to both send() and recv().

## DESCRIPTION

> This routine allows communications on a socket to be shut down one piece at a time rather than all at once. Use the shutdown() routine to create unidirectional connections rather than the normal bidirectional (full-duplex) connections.

> See also connect() 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 socket descriptor is invalid.
> [ENOTSOCK] | The descriptor references a file, not a socket.
> [ENOTCONN] | The specified socket is not connected.

# socket()

> Creates an end point for communication by returning a special kind of file descriptor called a socket descriptor, which is associated with a UCX socket device channel.

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

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int socket (int af, int type, int protocol);

## ARGUMENTS

> ### af

> The address format to be used in later references to the socket. Addresses specified in subsequent operations using the socket are interpreted according to this format. Currently, only AF_INET (internet style) addresses are supported.

> ### type

> The socket types are:
> - SOCK_STREAM --- Provides sequenced, reliable, two-way, connection-based byte streams with an available out-of-band data transmission mechanism.
> - SOCK_DGRAM --- Supports datagrams (connectionless, unreliable data transmission mechanism).
> - SOCK_RAW --- Provides access to internal network interfaces, and are available only to users with a system UIC or SYSPRV privilege.

> ### protocol

> The protocol to be used with the socket. Normally only a single protocol exists to support a particular socket type using a given address format. However, many protocols may exist, in which case a particular protocol must be specified with this argument. Use the protocol number that is specific to the communication domain in which communication takes place.

## DESCRIPTION

> This routine provides the primary mechanism for creating sockets. The type and protocol of the socket affect the way the socket behaves and how it can be used.

> The operation of sockets is controlled by socket-level options, defined in the file <socket.h>. Use the setsockopt() and getsockopt() routines to set and get options. Options other than SO_LINGER take an integer parameter that should be nonzero if the option is to be enabled, or 0 if it is to be disabled. SO_LINGER uses a linger structure parameter defined in <socket.h>.

> - SO_REUSEADDR --- Indicates that the rules used in validating addresses supplied in a bind() call should allow reuse of local addresses.
> - SO_KEEPALIVE --- Keeps connections alive by enabling the periodic transmission of messages on a connected socket. If the connected party fails to respond to these messages, the connection is considered broken and processes using the socket are notified through the error code SS$_LINKDISCON.
> - SO_DONTROUTE --- Indicates that outgoing messages should bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface according to the network portion of the destination address.
> - SO_LINGER --- Lingers on close if data is present. It controls the actions taken when unsent messages are queued on the socket and a close() is performed. When using the setsockopt() to set the linger values, the option value for the SO_LINGER command is the address of a linger structure (see Section 5.8.4).
>   If the socket promises reliable delivery of data and l_onoff is nonzero, the system will block the process on the attempt until it is able to transmit the data or until it decides it is unable to deliver the information. A timeout period, called the linger interval, is specified in l_linger. If l_onoff is set to 0 and a close is issued, the system processes the close in a manner that allows the process to continue as quickly as possible.
> - SO_BROADCAST --- Enables or disables broadcasting on the socket.

> See also accept(), bind(), connect(), listen(), read(), recv(), recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(), shutdown(), and write().

> See also getsockname() and getsockopt().

## Return Values

> x | A file descriptor that refers to the socket descriptor.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EAFNOSUPPORT] | The specified address family is not supported in this version of the system.
> [ESOCKTNOSUPPORT] | The specified socket type is not supported in this address family.
> [EPROTONOSUPPORT] | The specified protocol is not supported.
> [EPROTOTYPE] | Request for a type of socket for which there is no supporting protocol.
> [EMFILE] | The per-process descriptor table is full.
> [ENOBUFS] | No buffer space is available. The socket cannot be created.

# write()

> Writes a buffer of data to a socket or file.

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

## Format

> ### #include <unixio.h>

> ### int write (int d, void *buffer, int nbytes);

## ARGUMENTS

> ### d

> A descriptor that must refer to a socket or file.

> ### buffer

> The address of contiguous storage from which the output data is taken.

> ### nbytes

> The maximum number of bytes involved in the write operation.

## DESCRIPTION

> This routine attempts to write a buffer of data to a socket or file.

> See also socket().

## Return Values

> x | The number of bytes written to the socket or file.
> --1 | Error; errno is set to indicate the error.

## Errors

> You can set errno to the following values:
> [EBADF] | The d argument is not a valid descriptor open for writing.
> [EPIPE] | An attempt was made to write to a socket that is not open for reading by any process.
> [EFAULT] | Part of the array pointed to by iov or data to be written to the file points outside the process's allocated address space.
> [EWOULDBLOCK] | The NBIO (nonblocking) flag is set for the socket descriptor and the process is delayed during the write operation.
> [EINVAL] | The nbytes argument is negative.

# 6.2 Communication Support Routines

This section describes the communication support routines.

# decc$get_sdc()

> Returns the socket device channel (SDC) associated with a socket descriptor for direct use with DIGITAL TCP/IP Services for OpenVMS software.

## Format

> ### #include <socket.h>

> ### short int decc$get_sdc (int s);

## ARGUMENT

> ### s

> A socket descriptor.

## DESCRIPTION

> This routine returns the SDC associated with a socket. C Socket descriptors are normally used either as file descriptors or with one of the routines that takes an explicit socket descriptor as its argument. C Sockets are implemented using TCP/IP socket device channels. This routine returns the SDC used by a given socket descriptor so you can use the TCP/IP facilities directly by means of various I/O system services ($QIO).

> > Note

> > The 64-bit return from OpenVMS Alpha systems has zero-extended bits in the high 32 bits of R0.

## Return Values

> 0 | Indicates that s is not an open socket descriptor.
> x | The SDC number.

# gethostbyaddr()

> Searches the hosts database sequentially from the beginning of the database for a host record with a given address.

> The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYADDR subfunction code.

## Format

> ### #include <netdb.h>

> ### struct hostent *gethostbyaddr (char *addr, int len, int type);

## ARGUMENTS

> ### addr

> A pointer to a series of bytes in network order specifying the address of the host sought. This argument does not point to an ASCII string.

> ### len

> The number of bytes in the address pointed to by the addr argument.

> ### type

> The type of address format being sought. Currently, only AF_INET is supported.

## DESCRIPTION

> This routine finds the first host record in the hosts database with the given address.

> The gethostbyaddr() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.

## Return Values

> NULL | Indicates an error.
> x | A pointer to an object having the hostent structure. See Section 5.8.1 for a description of the hostent structure.

# gethostbyname()

> Searches the hosts database sequentially from the beginning of the database for a host record with a given name or alias. This routine also invokes the BIND resolver to query the appropriate name server if the information requested is not in the hosts database.

> The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETHOSTBYNAME subfunction code.

## Format

> ### #include <netdb.h>

> ### struct hostent *gethostbyname (char *name);

## ARGUMENT

> ### name

> A pointer to a null-terminated character string containing the name or an alias of the host sought.

## DESCRIPTION

> This routine finds the first host in the hosts database with the given name or alias.

> The gethostbyname() routine uses a common static area for its return values. This means that subsequent calls to this routine overwrite previously returned host entries. You must make a copy of the host entry if you want to save it.

## Return Values

> NULL | Indicates an error.
> x | A pointer to an object having the hostent structure. See Section 5.8.1 for a description of the hostent structure.

# gethostname()

> Returns the fully qualified name of the local host.

## Format

> ### #include <types.h>

> ### #include <socket.h>

> ### int gethostname (char *name, int namelen);

## ARGUMENTS

> ### name

> The address of a buffer where the name should be returned. The returned name is null-terminated unless sufficient space is not provided.

> ### namelen

> The size of the buffer pointed to by name.

## DESCRIPTION

> This routine returns the translation of the logical names UCX$INET_HOST and UCX$INET_DOMAIN when used with the UCX software.

## Return Values

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

## Errors

> You can set errno to the following values:
> [EFAULT] | The buffer described by name and namelen is not a valid, writable part of the user address space.

# getnetbyaddr()

> Searches the networks database sequentially from the beginning of the database for a network record with a given address.

> The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYADDR subfunction code.

## Format

> ### #include <netdb.h>

> ### struct netent *getnetbyaddr (long net, int type);

## ARGUMENTS

> ### net

> The network number, in host byte order, of the networks database entry required.

> ### type

> The type of network sought. Currently, only AF_INET is supported.

## DESCRIPTION

> This routine finds the first network record in the networks database with the given address.

> The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines will overwrite any previously returned network entry. You must make a copy of the network entry if you want to save it.

## Return Values

> NULL | Indicates end of file or an error.
> x | A pointer to an object having the netent structure. See Section 5.8.6 for a description of the netent structure.

# getnetbyname()

> Searches the networks database sequentially from the beginning of the database for a network record with a given name or alias.

> The $QIO equivalent is the IO$_ACPCONTROL function with the INETACP_FUNC$C_GETNETBYNAME subfunction code.

## Format

> ### #include <netdb.h>

> ### struct netent *getnetbyname (char *name);

## ARGUMENT

> ### name

> A pointer to a null-terminated character string of the name or an alias of the network sought.

## DESCRIPTION

> This routine finds the first host in the networks database with the given name or alias.

> The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines overwrite previously returned network entries. You must make a copy of the network entry if you want to save it.

## Return Values

> NULL | Indicates end of file or an error.
> x | A pointer to an object having the netent structure. See Section 5.8.6 for a description of the netent structure.

## Errors

> You can set errno to the following value:
> [EFAULT] | The buffer described by name is not a valid, writable part of the user address space.

# getnetent()

> Reads the next record in the networks database, opening the database if necessary.

## Format

> ### #include <netdb.h>

> ### struct netent *getnetent();

## DESCRIPTION

> This routine allows the records in the networks database to be read sequentially in the order in which they appear in the database.

> The getnetent(), getnetbyaddr(), and getnetbyname() routines all use a common static area for their return values. This means that subsequent calls to any of these routines overwrite previously returned network entries. You must make a copy of the network entry if you want to save it.

## Return Values

> NULL | Indicates end of file or an error.
> x | A pointer to an object having the netent structure. See Section 5.8.6 for a description of the netent structure.

# getpeername()

> Returns the name of the connected peer.

> The $QIO equivalent is the IO$_SENSEMODE or IO$_SENSECHAR function with the p4 argument.

## Format

> ### #include <types.h>

> ### #include <socket.h>

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

## ARGUMENTS

> ### s

> A socket descriptor created using socket().

> ### name

> A pointer to a buffer within which the peer name is to be returned.

> ### namelen

> An address of an integer that specifies the size of the name buffer. On return, it will be modified to reflect the actual length, in bytes, of the name returned.

## DESCRIPTION

> This routine returns the name of the peer connected to the socket descriptor specified.

> See also bind() socket() and getsockname().

## 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.
> [ENOTCONN] | The socket is not connected.
> [ENOBUFS] | Resources were insufficient in the system to perform the operation.
> [EFAULT] | The name parameter is not a valid part of the user address space.

# getprotobyname()

> Searches the protocols database until a matching protocol name is found or until end of file is encountered.

## Format

> ### #include <netdb.h>

> ### struct protoent *getprotobyname (char *name);

## ARGUMENT

> ### name

> A pointer to a string containing the desired protocol name.

## DESCRIPTION

> This routine returns a pointer to a protoent structure containing the broken-out fields of the requested line from the protocols database:

>     struct  protoent {
>             char   *p_name;       /* official name of protocol */
>             char   **p_aliases;   /* alias list */
>             long   p_proto;       /* protocol number */
>     };

> Previous | Next | Contents