# Compaq TCP/IP Services for OpenVMS
Sockets API and System Services Programming

Previous | Contents | Index

# getsockname()

> Returns the name associated with a socket.

> The $QIO equivalent is the IO$_SENSEMODE function with the p3 argument.

## Format

> #include <types.h>

> #include <socket.h>

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

## Arguments

> ### s

> A socket descriptor created with `socket()` function and bound to the socket name with the `bind()` function.

> ### name

> A pointer to the buffer in which `getsockname()` should return the socket name.

> ### namelen

> A pointer to an integer containing the size of the buffer pointed to by name. On return, the integer contains the actual size, in bytes, of the name returned.

## Description

> This function returns the current name for the specified socket descriptor. The name is a format specific to the address family (AF_INET) assigned to the socket.

> The `bind()` function, not the `getsockname()` function, makes the association of the name to the socket.

> Related Functions

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

## Return Values

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

## Errors

> EBADF | The descriptor is invalid.
> EFAULT | The name argument is not a valid part of the user address space.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The operation is not supported for this socket's protocol.

# getsockopt()

> Returns the options set on a socket.

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

## Format

> #include <types.h>

> #include <socket.h>

> int getsockopt ( int s, int level, int optname, char *optval, unsigned int *optlen );

## Arguments

> ### s

> A socket descriptor created by the `socket()` function.

> ### level

> The protocol level for which the socket options are desired. It can have one of the following values:

> SOL_SOCKET | Get the options at the socket level.
> p | Any protocol number. Get the options for protocol level specified by p. See the IN.H header file for the various IPPROTO values.

> ### optname

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

> For descriptions of the supported socket level options, see the description of `setsockopt()` in this chapter.

> ### optval

> Points to a buffer in which the value of the specified option should be placed by `getsockopt()` .

> ### optlen

> Points to an integer containing the size of the buffer pointed to by optval. On return, the integer is modified to contain the actual size of the option value returned.

## Description

> This function gets information on socket options. See the appropriate protocol for information about available options at each protocol level.

## Return Values

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

## Errors

> EACCES | The calling process does not have appropriate permissions.
> EBADF | The socket descriptor is invalid.
> EDOM | The send and receive timeout values are too large to fit in the timeout fields of the socket structure.
> EFAULT | The address pointed to by the optval argument is not in a valid (writable) part of the process space, or the optlen argument is not in a valid part of the process address space.
> EINVAL | The optval or optlen argument is invalid; or the socket is shut down.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTSOCK | The socket descriptor is invalid.
> ENOPROTOOPT | The option is unknown or the protocol is unsupported.
> EOPNOTSUPP | The operation is not supported by the socket protocol.
> ENOPROTOOPT | The option is unknown.
> ENOTSOCK | The socket descriptor is invalid.

# htonl()

> Converts longwords from host byte order to network byte order.

## Format

> #include <in.h>

> unsigned long int htonl ( unsigned long int hostlong );

## Argument

> ### hostlong

> A longword in host byte order (OpenVMS systems). All integers on OpenVMS systems are in host byte order unless otherwise specified.

## Description

> This function converts 32-bit unsigned integers from host byte order to network byte order.

> Network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network byte order.

> This function is most often used with internet addresses. Network byte order places the byte with the most significant bits at lower addresses, whereas OpenVMS systems place the most significant bits at the highest address.

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

## Return Value

> x | A longword in network byte order.

# htons()

> Converts short integers from host byte order to network byte order.

## Format

> #include <in.h>

> unsigned short int htons ( unsigned short int hostshort );

## Argument

> ### hostshort

> A short integer in host byte order (OpenVMS systems). All short integers on OpenVMS systems are in host byte order unless otherwise specified.

## Description

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

> Network byte order is the format in which data bytes are expected to be transmitted through a network. All hosts on a network should 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 OpenVMS systems differs from the network byte order.

> This function is most often used with ports as returned by `getservent()` . Network byte order places the byte with the most significant bits at lower addresses, whereas OpenVMS systems place the most significant bits at the highest address.

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

## Return Value

> x | A short integer in network byte order. Integers in network byte order cannot be used for arithmetic computation on OpenVMS systems.

# inet_addr()

> Converts internet addresses in text form into numeric (binary) internet addresses in dotted decimal format.

## Format

> #include <in.h>

> #include <inet.h>

> int inet_addr ( char *cp );

## Argument

> ### cp

> A pointer to a null-terminated character string containing an internet address in the standard internet dotted-decimal format.

## Description

> This function returns an internet address in network byte order when given an ASCII (null-terminated) string that represents the address in the internet standard dotted-decimal format as its argument.

> Internet addresses specified with the dotted-decimal format take one of the following forms:

>     a.b.c.d
>     a.b.c
>     a.b
>     a

> When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the 4 bytes of an internet address. Note that when an internet address is viewed as a 32-bit integer quantity on an OpenVMS system, the bytes appear in binary as `d.c.b.a` . That is, OpenVMS bytes are ordered from least significant to most significant.

> When only one part is given, the value is stored directly in the network address without any byte rearrangement.

> All numbers supplied as parts in a dotted-decimal address can be decimal, octal, or hexadecimal, as specified in the C language. (That is, a leading 0x or 0X implies hexadecimal; a leading 0 implies octal; otherwise, the number is interpreted as decimal.)

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

## Return Values

> -1 | Indicates that cp does not point to a proper internet address.
> x | An internet address in network byte order.

# inet_lnaof()

> Returns the local network address portion of an internet address.

## Format

> #include <in.h>

> #include <inet.h>

> int inet_lnaof ( struct in_addr in );

## Argument

> ### in

> An internet address.

## Description

> This function returns the local network address portion of a full internet address.

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

## Return Value

> x | The local network address portion of an internet address, in host byte order.

# inet_makeaddr()

> Returns an internet address based on a particular local address and a network.

## Format

> #include <in.h>

> #include <inet.h>

> struct in_addr inet_makeaddr ( int net, int lna );

## Arguments

> ### net

> An internet network address in host byte order.

> ### lna

> A local network address on network net in host byte order.

## Description

> This function combines the net and lna arguments into a single internet address.

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

## Return Value

> x | An internet address in network byte order.

# inet_netof()

> Returns the internet network address portion of an internet address.

## Format

> #include <in.h>

> #include <inet.h>

> int inet_netof ( struct in_addr in );

## Argument

> ### in

> An internet address.

## Description

> This function returns the internet network address (NET) portion of a full internet address.

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

## Return Value

> x | The internet network portion of an internet address, in host byte order.

# inet_network()

> Converts a null-terminated text string representing an internet address into a network address in local host format.

## Format

> #include <in.h>

> #include <inet.h>

> int inet_network ( char *cp );

## Argument

> ### cp

> A pointer to an ASCII (null-terminated) character string containing a network address in the dotted-decimal format.

## Description

> This function returns an internet network address as local host integer value when an ASCII string representing the address in the internet standard dotted-decimal format is given as its argument.

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

## Return Values

> -1 | Indicates that cp does not point to a proper internet network address.
> x | An internet network address, in local host order.

# inet_ntoa()

> Converts an internet address into a text string representing the address in the standard internet dotted-decimal format.

## Format

> #include <in.h>

> #include <inet.h>

> char *inet_ntoa ( struct in_addr in );

## Argument

> ### in

> An internet address in network byte order.

## Description

> This function converts an internet address into an ASCII (null-terminated) string that represents the address in standard internet dotted-decimal format.

> Because the string is returned in a static buffer that is overwritten by subsequent calls to `inet_ntoa()` , you should copy the string to a safe place.

## Return Value

> x | A pointer to a string containing the internet address in dotted-decimal format.

# ioctl()

> Controls I/O requests to obtain network information.

## Format

> #include <ioctl.h>

> int ioctl ( int s, int request, ... /* arg */ );

## Argument

> ### s

> Specifies the socket descriptor of the requested network device.

> ### request

> Specifies the type of `ioctl` command to be performed on the device. The request types are grouped as follows:
> - Socket operations
> - File operations
> - Interface operations
> - ARP cache operations
> - Routing table operations

> Refer to Appendix B for a complete list of `IOCTL` commands.

> ### arg

> Specifies arguments for this request. The type of arg is dependent on the specific `ioctl()` request and device to which the `ioctl` call is targeted.

## Description

> The `ioctl()` function performs a variety of control functions on devices. The functions performed are device-specific control functions. The request and arg arguments are passed to the file designated by fildes and then interpreted by the device driver. The basic I/O functions are performed through the `read()` and `write()` functions.

> Encoded in an `ioctl()` request is whether the argument is an in argument or an out argument, and the size of the arg argument in bytes. The macros and definitions used to specify an `ioctl()` request are located in the `IOCTL.H` header file.

## Return Values

> -1 | Error; `errno` is set to indicate the error.

## Errors

> EBADF | The fildes argument is not a valid open file descriptor.
> EINTR | A signal was caught during the `ioctl()` operation.
> If an underlying device driver detects an error, `errno` might be set to one of the following values:
> EINVAL | Either the request or the arg argument is not valid.
> ENOTTY | Reserved for Compaq use. The fildes argument is not associated with a character special device, or the specified request does not apply to the type of object that the fildes argument references.
> ENXIO | The request and arg arguments are valid for this device driver, but the service requested cannot be performed on the particular subdevice.

# listen()

> Converts an unconnected socket into a passive socket and indicates that the kernel should accept incoming connection requests directed to the socket.

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

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

## Format

> int listen ( int s, int backlog );

## Arguments

> ### s

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

> ### backlog

> The maximum number of pending connections that can be queued on the socket at any given time. The maximum number of pending connections can be set using the `sysconfig` utility to set the value of `somaxconn` . The default value for the maximum number of pending connections is 1024.

## Description

> This function creates a queue for pending connection requests on socket s with a maximum size equal to the value of backlog. Connections can then be accepted with the `accept()` function.

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

> Related Functions

> 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.
> EDESTADDRREQ | The socket is not bound to a local address, and the protocol does not support listening on an unbound socket.
> EINVAL | The socket is already connected, or the socket is shut down.
> ENOBUFS | The system has insufficient resources to complete the call.
> ENOTSOCK | The socket descriptor is invalid.
> EOPNOTSUPP | The referenced socket is not of a type that supports the operation `listen()` .

Previous | Next | Contents | Index