[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP TCP/IP Services for OpenVMS
Sockets API and System Services Programming


Previous Contents Index


inet_netof()

Returns the internet network address portion of an IP address.

Format

#include <in.h>

#include <inet.h>

int inet_netof ( struct in_addr in );


Argument

in

An IP address.

Description

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

Note

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

Return Value

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

inet_network()

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

Format

#include <in.h>

#include <inet.h>

int inet_network ( const 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 a 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 and I64 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 IP 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 IP address in network byte order.

Description

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

The string is returned in a static buffer that is overwritten by subsequent calls to inet_ntoa() . If you want to save the text string, you should copy it.


Return Value

x A pointer to a string containing the IP address in dotted-decimal format.

inet_ntop()

Converts a numeric address to a text string suitable for presentation.

Format

#include <inet.h>

const char *inet_ntop ( int af, const void *src, char *dst, size_t size );


Arguments

af

Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address.

src

Points to a buffer that contains the numeric IP address.

dst

Points to a buffer that is to contain the text string.

size

Specifies the size of the buffer pointed to by the dst parameter. For IPv4 addresses, the minimum buffer size is 16 bytes. For IPv6 addresses, the minimum buffer size is 46 bytes. INET_ADDRSTRLEN constants are defined in the IN.H header file. INET6_ADDRSTRLEN constants are defined in IN6.H.

Description

This function converts a numeric IP address value to a text string.

Return Values

Pointer to the buffer containing the text string Success
Pointer to the buffer containing NULL Failure

inet_pton()

Converts an address in its standard text presentation form into its numeric binary form, in network byte order.

Format

#include <inet.h>

int inet_pton ( int af, const char *src, void *dst );


Arguments

af

Specifies the address family. Valid values are AF_INET for an IPv4 address and AF_INET6 for an IPv6 address.

src

Points to the address text string to be converted.

dst

Points to a buffer that is to contain the numeric address.

Description

This function converts a text string to a numeric value in network byte order.
  • If the af parameter is AF_INET, the function accepts a string in the standard IPv4 dotted-decimal format:


    
           ddd.ddd.ddd.ddd
    
    

    In this format, ddd is a one- to three-digit decimal number between 0 and 255.
  • If the af parameter is AF_INET6, the function accepts a string in the following format:


    x:x:x:x:x:x:x:x
    

    In this format, x is the hexadecimal value of a 16-bit piece of the address.
    IPv6 addresses can contain long strings of zero (0) bits. To make it easier to write these addresses, you can use double-colon characters (::) one time in an address to represent 1 or more 16-bit groups of zeros.
  • For mixed IPv4 and IPv6 environments, the following format is also accepted:


    x:x:x:x:x:x:ddd.ddd.ddd.ddd
    

    In this format, x is the hexadecimal value of a 16-bit piece of the address, and ddd is a one- to three-digit decimal value between 0 and 255 that represents the IPv4 address.

The calling application is responsible for ensuring that the buffer referred to by the dst parameter is large enough to hold the numeric address. AF_INET addresses require 4 bytes and AF_INET6 addresses require 16 bytes.


Return Values

1 Indicates success.
0 Indicates that the input string is neither a valid IPv4 dotted-decimal string nor a valid IPv6 address string.
-1 Indicates a failure. errno is set to the following value.

Errors

EAFNOSUPPORT The address family specified in the af parameter is unknown.

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 supported 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

This function performs a variety of device-specific functions. The request and arg arguments are passed to the file designated by the s argument 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 s argument is not a valid socket 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 HP use. The s argument is not associated with a network device, or the specified request does not apply to the specific network device.
ENXIO The request and arg arguments are valid for this device driver, but the service requested cannot be performed on the device.

listen()

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

The $QIO equivalent is the IO$_SETMODE service.


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 by specifying the value of the socket subsystem attribute somaxconn . (Refer to the HP TCP/IP Services for OpenVMS Tuning and Troubleshooting guide for more information.) 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() .

ntohl()

Converts longwords from network byte order to host byte order.

Format

#include <in.h>

unsigned long ntohl ( unsigned long netlong );


Argument

netlong

A longword in network byte order. Integers in network byte order cannot be used for arithmetic computation on OpenVMS systems.

Description

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

Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address.

This function can be used to convert IP addresses from network byte order to host byte order.


Return Value

x A longword in host byte order.

ntohs()

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

Format

#include <in.h>

unsigned short ntohs ( unsigned short netshort );


Argument

netshort

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

Description

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

Data bytes transmitted over the network are expected to be in network byte order. Some hosts, like OpenVMS, have an internal data representation format that is different from the network byte order; this is called the host byte order. Network byte order places the byte with the most significant bits at lower addresses, but OpenVMS host byte order places the most significant bits at the highest address.

This function can be used to convert port numbers returned by getservent() from network byte order to host byte order.


Return Value

x A short integer in host byte order (OpenVMS systems).

poll()

Monitors conditions on multiple file descriptors.

Format

#include <poll.h>

int poll (struct pollfd fds[], nfds_t nfds, int timeout);


Arguments

fds

An array of pollfd structures, one for each file descriptor of interest. Each pollfd structure includes the following members:
int fd The file descriptor
int events The requested conditions
int revents The reported conditions

nfds

The number of pollfd structures in the fds array.

timeout

The maximum length of time (in milliseconds) to wait for one of the specified events to occur.

Description

This function provides applications with a mechanism for multiplexing input/output over a set of file descriptors. For each member of the array pointed to by fds, poll() examines the given file descriptor for the events specified in events . The number of pollfd structures in the fds array is specified by nfds. The poll() function identifies those file descriptors on which an application can read or write data, or on which certain events have occurred.

The fds argument specifies the file descriptors to be examined and the events of interest for each file descriptor. It is a pointer to an array with one member for each open file descriptor of interest. The array's members are pollfd structures within which fd specifies an open file descriptor, and events and revents are bitmasks constructed by OR-ing a combination of the following event flags:

  • POLLIN
    Normal data may be received without blocking.
  • POLLRDNORM
    Same as POLLIN.
  • POLLRDBAND
    Out-of-band data may be received without blocking.
  • POLLPRI
    Same as POLLRDBAND
  • POLLOUT
    Normal data may be written without blocking.
  • POLLWRNORM
    Same as POLLOUT.
  • POLLWRBAND
    Out-of-band data may be written without blocking.

If the value of fd is less than 0, events is ignored and revents is set to 0 in that entry on return from poll() . In each pollfd structure, poll() clears the revents member except that where the application requested a report on a condition by setting one of the bits of events listed above, poll() sets the corresponding bit in revents if the requested condition is true.

If none of the defined events have occurred on any selected file descriptor, poll() waits at least timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of timeout is 0, poll() returns immediately. If the value of timeout is -1, poll() blocks until a specified event occurs or until the call is interrupted.

The poll() function is not affected by the O_NONBLOCK flag.

On OpenVMS, the poll() function supports sockets only.

Note

HP recommends using the select() function for optimal performance. The poll() function is provided to ease the porting of existing applications from other platforms.

Return Values

positive value Upon successful completion, the total number of file descriptors selected (that is, file descriptors for which the revents member is nonzero).
0 Successful completion. The call timed out and no file descriptors were selected.
-1 The poll() function failed. The errno is set to indicate the error.

Errors

EAGAIN The allocation of internal data structures failed but a subsequent request may succeed.
EINTR A signal was caught during the poll() function.

read()

Reads data from a socket or file.

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

This function reads bytes from a socket or file and places them in a user-defined buffer.

If the end of file is not reached, the read() function returns nbytes. If the end of file occurs during the read() function, it returns the number of bytes read.

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

Related Functions

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 socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The data was specified to be received into a nonexistent or protected part of the process address space.
EINTR A signal interrupted the read() function before any data was available.
EINVAL The MSG_OOB flag is set and no out-of-band data is available.
ENOBUFS The system has insufficient resources to complete the call.
ENOMEM The system did not have sufficient memory to fulfill the request.
ENOTCONN A receive is attempted on a connection-oriented socket that is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The specified flags are not supported for this socket type or protocol.
EWOULDBLOCK The socket is marked nonblocking, and no data is waiting to be received.


Previous Next Contents Index