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


Previous Contents Index


setsockopt()

Sets options on a socket.

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


Format

#include <types.h>

#include <socket.h>

int setsockopt (int s, int level, int optname, char *optval, int optlen);


Arguments

s

A socket descriptor created by socket().

level

The protocol level for which the socket options are to be modified. It can have one of the following values:
SOL_SOCKET Set the options at the socket level.
p Any protocol number. Set the options for protocol level p. See the <in.h> header file for the various IPPROTO values.

optname

Interpreted by the protocol specified in level. Options at each protocol level are documented with the protocol.

Table 6-3 lists the options available at the socket level.

Table 6-3 Socket Options
Socket Option Description
SO_BROADCAST Permits the sending of broadcast messages. Takes an integer parameter and requires a system user identification code (UIC) or SYSPRV, BYPASS, or OPER privilege. Optional for connectionless datagram.
SO_DONTROUTE Indicates that outgoing messages should bypass the standard routing facilities. Instead, the messages are directed to the appropriate network interface according to the network portion of the destination address.
SO_ERROR Obtains the socket error status and clears the error on the socket.
TCPIP$C_FULL_DUPLEX_CLOSE When set before a close operation, both receive and transmit sides of the communications are closed.
SO_KEEPALIVE Keeps connections active. Enables the periodic transmission of messages on a connected socket. If the connected socket fails to respond to the messages, the connection is broken.
SO_LINGER Lingers on a close() function if data is present. Controls the action taken when unsent messages queue on a socket and a close() function is performed. Uses a linger structure parameter defined in <socket.h> to specify the state of the option and linger interval.

If SO_LINGER is specified, the system blocks the process during the close() function until it can transmit the data or until the time expires. If the option is not specified and a close() function is issued, the system allows the process to continue as quickly as possible.

SO_OOBINLINE Leaves the received out-of-band (OOB) data (data marked urgent) in line. Takes an integer parameter.
SO_RCVBUF Sets the receive buffer size. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege.
SO_RCVTIMEO For Compaq use only. Sets the timeout value for a recv() operation.
SO_REUSEADDR Specifies that the rules used in validating addresses supplied by a bind() function should allow reuse of local addresses. Takes an integer value.
SO_REUSEPORT Allows more than one process to receive UDP datagrams destined for the same port. The bind() call that binds a process to the port must be preceded by a setsockopt() call specifying this option.
SO_SHARE Allows multiple processes to share the socket.
SO_SNDBUF Sets the send buffer size. Takes an integer parameter and requires a system UIC or SYSPRV, BYPASS, or OPER privilege. Optional for a connectionless datagram.
SO_SNDLOWAT Sets the low-water mark for a send() operation. Takes an integer parameter.
SO_SNDTIMEO For Compaq use only. Sets the timeout value for a send() operation.
SO_USELOOPBACK For Compaq use only. Valid for routing sockets. Determines if a sending socket receives a copy of its own message. Used when a set request on another socket type is ignored.

Table 6-4 lists the TCP options available at the socket level.

Table 6-4 TCP Options
TCP Option Description
TCP_KEEPCNT When the SO_KEEPALIVE option is enabled, specifies the maximum number of keepalive probes to be sent. Default: 8. Takes an integer value, with a range of 1 to TCP_KEEPCNT.
TCP_KEEPIDLE When the SO_KEEPALIVE option is enabled, specifies the number of seconds of idle time between keepalive probes. Default: 2 hours. Takes an integer value in the range of 1 to n, where n is TCP_KEEPIDLE divided by PR_SLOWHZ.
TCP_KEEPINIT Specifies the number of seconds to wait before the connect attempt times out. Default: 75 seconds. For passive connections, the value is inherited from the listening socket. Takes an integer value in the range of 1 to n, where n is TCP_KEEPINIT divided by PR_SLOWHZ.
TCP_KEEPINTVL When the SO_KEEPALIVE option is enabled, specifies the number of seconds to wait before retransmitting a keepalive probe. Default: 75 seconds. Takes an integer value in the range of 1 to n, where n is TCP_KEEPINTVL divided by PR_SLOWHZ.
TCP_NODELAY Specifies that the send() operation will not be delayed to merge packets.
TCP_MAXSEG Sets the maximum transmission unit (MTU) of a TCP segment to a specified integer value from 1 to 65,535. Default: 576 bytes. Can only be set before a listen() or connect() operation on the socket. For passive connections, the value is obtained from the listening socket.

Note that TCP does not use an MTU value that is less than 32 or greater than the local network's MTU. Setting the option to zero results in the default behavior.

TCP_NODELACK When specified, disables the algorithm that gathers outstanding data that has not been acknowledged and sends it in a single packet when acknowledgement is received. Takes an integer value.

Under most circumstances, TCP sends data when it is presented. When outstanding data has not yet been acknowledged, TCP gathers small amounts of the data into a single packet and sends it when an acknowledgement is received. This functionality can cause significant delays for some clients (such as windowing systems that send a stream of events from the mouse that do not expect replies).

Table 6-5 describes the IP options available at the socket level.

Table 6-5 IP Options
IP Option Description
IP_ADD_MEMBERSHIP Adds the host to the membership of a multicast group.

A host must become a member of a multicast group before it can receive datagrams sent to the group. Membership is associated with a single interface; programs running on multihomed hosts may need to join the same group on more than one interface. Up to IP_MAX_MEMBERSHIPS (currently 20) memberships may be added on a single socket.

IP_DROP_MEMBERSHIP Removes the host from the membership of a multicast group.
IP_HDRINCL If specified, the IP header is not prepended to the outgoing packet.
IP_MULTICAST_IF For hosts with multiple interfaces. When specified, each multicast transmission is sent from the primary network interface. Overrides the default for subsequent transmissions from a given socket.
IP_MULTICAST_LOOP Disables loopback of local delivery.

If a multicast datagram is sent to a group of which the sending host is a member, a copy of the datagram is looped back by the IP layer for local delivery (default). To disable the loopback delivery, specify the value 0.

IP_MULTICAST_TTL Specifies the time-to-live (TTL) value for outgoing multicast datagrams. Takes an integer value between 0 and 255:
Value Action
0 Restricts distribution to applications running on the local host.
1 Forwards the multicast datagram to hosts on the local subnet.
1---255 With a multicast router attached to the sending host's network, forwards multicast datagrams beyond the local subnet.

Multicast routers forward the datagram to known networks that have hosts belonging to the specified multicast group. The TTL value is decremented by each multicast router in the path. When the TTL value is decremented to 0, the datagram is no longer forwarded.

IP_OPTIONS Provides IP options to be transmitted in the IP header of each outgoing packet.
IP_RECVDSTADDR Enables a SOCK_DGRAM socket to receive the destination IP address for a UDP datagram.
IP_RECVOPTS Enables a SOCK_DGRAM socket to receive IP options.
IP_TTL Time to live (TTL) for a datagram.
IP_TOS Type of service (1-byte value).

optval

Points to a buffer containing the parameters of the specified option.

All socket level options other than SO_LINGER should be nonzero if the option is to be enabled, or zero if it is to be disabled.

SO_LINGER uses a linger structure parameter defined in the <socket.h> file. This structure specifies the desired state of the option and the linger interval. The option value for the SO_LINGER command is the address of a linger structure. See Section 5.8.4 for a description of the linger structure.

If the socket promises reliable delivery of data and l_onoff is nonzero, the system blocks the process on the close() 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 zero and a close() is issued, the system processes the close in a manner that allows the process to continue as quickly as possible.

optlen

An integer containing the size of the buffer pointed to by optval.

Description

This routine manipulates options associated with a socket. Options can exist at multiple protocol levels. They are always present at the uppermost socket level.

When manipulating socket options, specify the level at which the option resides and the name of the option. To manipulate options at the socket level, specify level as SOL_SOCKET. To manipulate options at any other level, supply the protocol number of the appropriate protocol controlling the option. For example, to indicate that an option is to be interpreted by TCP, set the level to the protocol number (IPPROTO_TCP) of TCP. See <in.h> for the various IPPROTO values.


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.
[ENOPROTOOPT] The option is unknown.
[EFAULT] The optname parameter is not a valid part of the user address space.

vaxc$get_sdc()

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

Note

This routine only works with VAX C. Use the decc$get_sdc() routine with DEC C.

Format

#include <socket.h>

short int vaxc$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.


Chapter 7
Error Codes

This chapter contains a table of C Socket error codes and their OpenVMS system service equivalents. The C Socket routines use the DEC C compiler.

Table 7-1 Translation of Socket Error Codes to OpenVMS Error Codes
C Socket (DEC C)
Error Code
Meaning OpenVMS
System Service
Error Code
0 (success) SS$_NORMAL
1 EPERM Not owner SS$_ABORT
2 ENOENT No such file or directory SS$_ABORT
3 ESRCH No such process SS$_NOSUCHNODE
4 EINTR Interrupted system call SS$_ABORT
5 EIO I/O error SS$_ABORT
6 ENXIO No such device or address SS$_NOSUCHDEV
7 E2BIG Argument list too long SS$_ABORT
8 ENOEXEC Execution format error SS$_ABORT
9 EBADF Bad file number SS$_BADPARAM
10 ECHILD No children SS$_ABORT
11 EAGAIN No more processes SS$_ABORT
12 ENOMEM Not enough core SS$_INSFMEM
13 EACCES Permission denied SS$_ABORT
14 EFAULT Bad address SS$_ACCVIO
15 ENOTBLK Block device required SS$_ABORT
16 EBUSY Mount device busy SS$_ABORT
17 EEXIST File exists SS$_FILALRACC
18 EXDEV Cross-device link SS$_ABORT
19 ENODEV No such device SS$_ABORT
20 ENOTDIR Not a directory SS$_ABORT
21 EISDIR Is a directory SS$_ABORT
22 EINVAL Invalid argument SS$_BADPARAM
23 ENFILE File table overflow SS$_ABORT
24 EMFILE Too many open files SS$_ABORT
25 ENOTTY Not a typewriter SS$_ABORT
26 ETXTBSY Text file busy SS$_ABORT
27 EFBIG File too large SS$_ABORT
28 ENOSPC No space left on device SS$_ABORT
29 ESPIPE Illegal seek SS$_ABORT
30 EROFS Read-only file system SS$_ABORT
31 EMLINK Too many links SS$_ABORT
32 EPIPE Broken pipe SS$_LINKDISCON
33 EDOM Argument too large SS$_BADPARAM
34 ERANGE Result too large SS$_TOOMUCHDATA
35 EWOULDBLOCK Operation would block SS$_SUSPENDED
36 EINPROGRESS Operation now in progress SS$_ABORT
37 EALREADY Operation already in progress SS$_ABORT
38 ENOTSOCK Socket operation on non-socket SS$_NOTNETDEV
39 EDESTADDRREQ Destination address required SS$_NOSUCHNODE
40 EMSGSIZE Message too long SS$_TOOMUCHDATA
41 EPROTOTYPE Protocol wrong type for socket SS$_PROTOCOL
42 ENOPROTOOPT Protocol not available SS$_PROTOCOL
43 EPROTONOSUPPORT Protocol not supported SS$_PROTOCOL
44 ESOCKTNOSUPPORT Socket type not supported SS$_PROTOCOL
45 EOPNOTSUPP Operation not supported on socket SS$_ILLCNTRFUNC
46 EPFNOSUPPORT Protocol family not supported SS$_PROTOCOL
47 EAFNOSUPPORT Address family not supported SS$_PROTOCOL
48 EADDRINUSE Address already in use SS$_DUPLNAM
49 EADDRNOTAVAIL Requested address cannot be assigned SS$_IVADDR
50 ENETDOWN Network is down SS$_UNREACHABLE
51 ENETUNREACH Network is unreachable SS$_UNREACHABLE
52 ENETRESET Network dropped connection on reset SS$_RESET
53 ECONNABORTED Software caused connection abort SS$_LINKABORT
54 ECONNRESET Connection reset by peer SS$_CONNECFAIL
55 ENOBUFS No buffer space available SS$_INSFMEM
56 EISCONN Socket is already connected SS$_FILALRACC
57 ENOTCONN Socket is not connected SS$_NOLINKS
58 ESHUTDOWN Cannot send after socket shutdown SS$_SHUT
59 ETOOMANYREFS Too many references, cannot splice SS$_ABORT
60 ETIMEDOUT Connection timed out SS$_TIMEOUT
61 ECONNREFUSED Connection refused SS$_REJECT
62 ELOOP Too many levels of symbolic links SS$_ABORT
63 ENAMETOOLONG File name too long SS$_ABORT
64 EHOSTDOWN Host is down SS$_SHUT
65 EHOSTUNREACH No route to host SS$_UNREACHABLE


Previous Next Contents Index