Socket functions let you write network programs that can be
easily ported to other operating systems.
1 – accept()
Accepts a connection on a passive socket.
The $QIO equivalent is the IO$_ACCESS system service with the
IO$M_ACCEPT modifier.
Format
#include <types.h>
#include <socket.h>
int accept ( int s, struct sockaddr *addr, int *addrlen );
(_DECC_V4_SOURCE)
int accept ( int s, struct sockaddr *addr, size_t *addrlen );
(not_DECC_V4_SOURCE)
1.1 – Arguments
s
A socket descriptor returned by socket(), subsequently bound to
an address with bind(), which is listening for connections after
a listen().
addr
A result argument filled in with the address of the connecting
entity, as known to the TCP/IP kernel. The exact format of the
structure to which the address parameter points is determined by
the address family. Specify either the IPv4 address family (AF_
INET) or the IPv6 address family (AF_INET6).
addrlen
A value/result argument. It should initially contain the size of
the structure pointed to by addr. On return it will contain the
actual length, in bytes, of the sockaddr structure that has been
filled in by the TCP/IP kernel.
1.2 – Description
This function completes the first connection on the queue
of pending connections, creates a new socket with the same
properties as s, and allocates and returns a new descriptor
for the socket. If no pending connections are present on the
queue and the socket is not marked as nonblocking, accept()
blocks the caller until a connection request is present. If the
socket is marked nonblocking by using a setsockopt() call and no
pending connections are present on the queue, accept() returns
an error. You cannot use the accepted socket to accept subsequent
connections. The original socket s remains open (listening) for
other connection requests. This call is used with connection-
based socket types (SOCK_STREAM).
You can select a socket for the purposes of performing an accept
by selecting it for a read.
Related Functions
See also bind(), connect(), listen(), select(), and socket().
1.3 – Return Values
x A positive integer that is a descriptor for
the accepted socket.
-1 Error; errno is set to indicate the error.
1.4 – Errors
EBADF The socket descriptor is invalid.
ECONNABORTED A connection has been aborted.
EFAULT The addr argument is not in a writable part of
the user address space.
EINTR The accept() function was interrupted by a
signal before a valid connection arrived.
EINVAL The socket is not accepting connections.
EMFILE There are too many open file descriptors.
ENFILE The maximum number of file descriptors in the
system is already open.
ENETDOWN TCP/IP Services was not started.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The reference socket is not of type SOCK_
STREAM.
EPROTO A protocol error occurred.
EWOULDBLOCK The socket is marked nonblocking, and no
connections are present to be accepted.
2 – bind()
Binds a name to a socket.
The $QIO equivalent is the IO$_SETMODE system service with the p3
argument.
Format
#include <types.h>
#include <socket.h>
int bind ( int s, struct sockaddr *name, int namelen );
(_DECC_V4_SOURCE)
int bind ( int s, const struct sockaddr *name, size_t namelen
); (not_DECC_V4_SOURCE)
2.1 – Arguments
s
A socket descriptor created with the socket() function.
name
Address of a structure used to assign a name to the socket in
the format specific to the family (AF_INET or AF_INET6) socket
address.
namelen
The size, in bytes, of the structure pointed to by name.
2.2 – Description
This function assigns a port number and IP address to an unnamed
socket. When a socket is created with the socket() function, it
exists in a name space (address family) but has no name assigned.
The bind() function requests that a name be assigned to the
socket.
Related Functions
See also connect(), getsockname(), listen(), and socket().
2.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
2.4 – Errors
EACCESS The requested address is protected, and the
current user has inadequate permission to
access it.
EADDRINUSE The specified internet address and ports are
already in use.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The specified address is invalid for the
address family of the specified socket.
EBADF The socket descriptor is invalid.
EDESTADDRREQ The address argument is a null pointer.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket is already bound to an address and
the protocol does not support binding to a new
address, the socket has been shut down, or the
length or the namelen argument is invalid for
the address family.
EISCONN The socket is already connected.
EISDIR The address argument is a null pointer.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket type of the specified socket does
not support binding to an address.
3 – close()
Closes a connection and deletes a socket descriptor.
The $QIO equivalent is the $DASSGN system service.
Format
#include <unixio.h>
int close ( s );
3.1 – Argument
s
A socket descriptor.
3.2 – Description
This function deletes a descriptor from the per-process object
reference table. Associated TCP connections close first.
If a call to connect() fails for a socket in connection mode,
applications should use close() to deallocate the socket and
descriptor.
Related Functions
See also accept(), socket(), and write().
3.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
3.4 – Errors
EBADF The socket descriptor is invalid.
EINTR The close() function was interrupted by a
signal that was caught.
4 – connect()
Initiates a connection on a socket.
The $QIO equivalent is the IO$_ACCESS system service.
Format
#include <types.h>
#include <socket.h>
int connect ( int s, struct sockaddr *name, int namelen );
(_DECC_V4_SOURCE)
int connect ( int s, const struct sockaddr *name, size_t
namelen ); (not_DECC_V4_SOURCE)
4.1 – 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 or
AF_INET6).
namelen
The size, in bytes, of the structure pointed to by name.
4.2 – Description
This function initiates a connection on a socket.
If s is a socket descriptor of type SOCK_DGRAM, then this call
permanently specifies the peer where the data is sent. If s is of
type SOCK_STREAM, then this call attempts to make a connection to
the specified socket.
If a call to connect() fails for a connection-mode socket,
applications should use close() to deallocate the socket
and descriptor. If attempting to reinitiate the connection,
applications should create a new socket.
Related Functions
See also accept(), select(), socket(), getsockname(), and
shutdown().
4.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
4.4 – Errors
EADDRINUSE Configuration problem. There are insufficient
ports available for the attempted connection.
The inet subsystem attribute ipport_
userreserved should be increased.
EADDRNOTAVAIL The specified address is not available from
the local machine.
EAFNOSUPPORT The addresses in the specified address family
cannot be used with this socket.
EALREADY A connection request is already in progress
for the specified socket.
EBADF The socket descriptor is invalid.
ECONNREFUSED The attempt to connect was rejected.
EFAULT The name argument is not a valid part of the
user address space.
EHOSTUNREACH The specified host is not reachable.
EINPROGRESS O_NONBLOCK is set for the file descriptor
for the socket, and the connection cannot be
immediately established; the connection will
be established asynchronously.
EINTR The connect() function was interrupted by a
signal while waiting for the connection to be
established. Once established, the connection
may continue asynchronously.
EINVAL The value of the namelen argument is invalid
for the specified address family, or the sa_
family member in the socket address structure
is invalid for the protocol.
EISCONN The socket is already connected.
ELOOP Too many symbolic links were encountered in
translating the file specification in the
address.
ENETDOWN The local network connection is not
operational.
ENETUNREACH No route to the network or host is present.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket is listening and cannot be
connected.
EPROTOTYPE The specified address has a different type
than the socket bound to the specified peer
address.
ETIMEDOUT The connection request timed out without
establishing a connection.
EWOULDBLOCK The socket is nonblocking, and the connection
cannot be completed immediately. It is
possible to use the select() function to
select the socket for writing.
5 – decc$get_sdc()
Returns the socket device's OpenVMS I/O channel (SDC) associated
with a socket descriptor.
Format
#include <socket.h>
short int decc$get_sdc ( int s );
5.1 – Argument
s
A socket descriptor.
5.2 – Description
This function returns the SDC associated with a socket. Normally,
socket descriptors are used either as file descriptors or with
one of the functions that takes an explicit socket descriptor
as its argument. Sockets are implemented using TCP/IP device
sockets. This function returns the SDC used by a given socket
descriptor so you can directly access the TCP/IP facilities by
means of $QIO system services.
5.3 – Return Values
0 Indicates that s is not an open socket
descriptor.
x The SDC number.
6 – decc$socket_fd
Returns the socket descriptor associated with a Socket Device
Channel (SDC) for direct use with the OpenVMS C Run-Time Library.
Format
#include <socket.h>
int decc$socket_fd (int channel);
6.1 – Argument
channel
A valid SDC.
6.2 – Description
This function associates a valid socket channel with an HP
C run-time library file descriptor, and returns the file
descriptor. The file descriptor can then be used with any HP C
run-time library function that takes a file descriptor or socket
descriptor as an input parameter.
6.3 – Return Values
x The socket descriptor.
-1 Indicates an error; the socket descriptor
cannot be allocated.
7 – endhostent()
Closes hosts database file.
Format
#include <netdb.h>
void endhostent (void);
7.1 – Description
This function closes the hosts database file
(TCPIP$ETC:IPNODES.DAT), previously opened with a
gethostbyaddr(), gethostent(), or gethostbyname() function call.
If the most recent sethostent() function call is executed with
a nonzero stay_open parameter, the endhostent() function does
not close the hosts database file. You cannot close the hosts
database file until you make a call to exit(). A second call
to sethostent() is issued with a stay_open parameter equal
to 0 (zero). This ensures that a subsequent endhostent() call
succeeds.
Related Functions
See also gethostbyaddr(), gethostent(), and gethostbyname().
8 – endnetent()
Closes the networks database file.
Format
#include <netdb.h>
void endnetent (void);
8.1 – Description
This function closes the networks database file
(TCPIP$SYSTEM:NETWORKS.DAT), previously opened with the
getnetent(), setnetent(), getnetbyaddr(), or getnetbyname()
function.
Related Functions
See also getnetent(), getnetbyaddr(), getnetbyname(), and
setnetent().
9 – endprotoent()
Resets the index for the protocols table.
Format
#include <netdb.h>
void endprotoent (void);
9.1 – Description
This function resets the index for the protocols table
previously accessed with a getprotoent(), getprotobyname(), or
getprotobynumber() function call.
Related Functions
See also getprotobyname(), getprotoent(), and
getprotobynumber().
10 – endservent()
Closes the services database file.
Format
#include <netdb.h>
void endservent (void);
10.1 – Description
This function closes the services database file
(TCPIP$ETC:SERVICES.DAT), previously opened with the
getservent(), getservbyname(), or getservbyport() function.
Related Functions
See also getservent(), getservbyname(), and getservbyport().
11 – freeaddrinfo()
Frees system resources used by an address information structure.
Format
#include <netdb.h>
void freeaddrinfo ( struct addrinfo *ai );
11.1 – Arguments
ai
Points to an addrinfo structure to be freed. The NETDB.H header
file defines the addrinfo structure.
11.2 – Description
This function frees an addrinfo structure and any dynamic storage
pointed to by the structure. The process continues until the
function encounters a NULL ai_next pointer.
12 – gai_strerror()
Provides a descriptive text string that corresponds to an EAI_xxx
error value.
Format
#include <netdb.h>
const char *gai_strerror ( int ecode );
12.1 – Arguments
ecode
The ecode argument is one of the EAI_xxx values defined for the
getaddrinfo() and getnameinfo() functions.
The values for ecode are:
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags parameter had an invalid value.
EAI_FAIL A nonrecoverable error occurred when attempting
to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither nodename nor servname
were supplied. At least one of these must be
supplied.
EAI_SERVICE The service passed was not recognized for the
specified socket type.
EAI_SOCKTYPE The intended socket type was not recognized.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
12.2 – Description
This function returns a descriptive text string that corresponds
to an EAI_xxx error value. The return value points to a string
that describes the error. If the argument is not one of the EAI_
xxx values, the function returns a pointer to a string whose
contents indicate an unknown error.
For a complete list of error codes, see Error Codes.
12.3 – Return Values
x text string
-1 Failure
13 – getaddrinfo()
Takes a service location (nodename) or a service name (servname),
or both, and returns a pointer to a linked list of one or more
structures of type addrinfo.
Format
#include <socket.h>
#include <netdb.h>
int getaddrinfo ( const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo
**res );
13.1 – Arguments
nodename
Points to a network node name, alias, or numeric host address
(for example, an IPv4 dotted-decimal address or an IPv6
hexadecimal address). An IPv6 nonglobal address with an intended
scope zone may also be specified. This is a null-terminated
string or NULL. NULL means the service location is local to the
caller. The nodename and servname arguments must not both be
NULL.
servname
Points to a network service name or port number. This is a null-
terminated string or NULL; NULL returns network-level addresses
for the specified nodename. The nodename and servname arguments
must not both be NULL.
hints
Points to an addrinfo structure that contains information about
the type of socket, address family, or protocol the caller
supports. The NETDB.H header file defines the addrinfo structure.
If hints is a null pointer, the behavior is the same as if
addrinfo contained the value 0 for the ai_flags, ai_socktype
and ai_protocol members and AF_UNSPEC for the ai_family member.
res
Points to a linked list of one or more addrinfo structures.
13.2 – Description
This function takes a service location (nodename) or a service
name (servname), or both, and returns a pointer to a linked list
of one or more structures of type addrinfo. Its members specify
data obtained from the local hosts database TCPIP$ETC:IPNODES.DAT
file, the local TCPIP$HOSTS.DAT file, or one of the files
distributed by DNS/BIND.
The NETDB.H header file defines the addrinfo structure.
If the hints argument is non-NULL, all addrinfo structure members
other than the following members must be zero or a NULL pointer:
o ai_flags
Controls the processing behavior of getaddrinfo(). See Member
Values for a complete description of the flags.
o ai_family
Specifies to return addresses for use with a specific protocol
family.
- If you specify a value of AF_UNSPEC, getaddrinfo() returns
addresses for any protocol family that can be used with
nodename or servname.
- If the value is not AF_UNSPEC and ai_protocol is not zero,
getaddrinfo() returns addresses for use only with the
specified protocol family and protocol.
- If the application handles only IPv4, set this member of
the hints structure to PF_INET.
o ai_socktype
Specifies a socket type for the given service. If you
specify a value of 0, you will accept any socket type. This
resolves the service name for all socket types and returns all
successful results.
o ai_protocol
Specifies a network protocol. If you specify a value of 0, you
will accept any protocol. If the application handles only TCP,
set this member to IPPROTO_TCP.
Member Values describes the values for ai_flags members.
Table 4-1 ai_flags Member Values
Flag Value Description
AI_V4MAPPED If ai_family is AF_INET, the flag is ignored.
If ai_family is AF_INET6, getaddrinfo() searches
for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, returns IPv6
addresses; no search for A records is
performed.
o If no AAAA records are found, searches for A
records.
o If A records found, returns IPv4-mapped IPv6
addresses.
o If no A records found, returns a NULL
pointer.
AI_ALL| If ai_family is AF_INET, the flag is ignored.
AI_V4MAPPED
If the ai_family is AF_INET6, getaddrinfo()
searches for AAAA records.
The lookup sequence is:
1. Local hosts database
2. TCPIP$ETC:IPNODES.DAT
3. BIND database
The lookup for a particular type of record,
for example an AAAA record, will be performed
in each database before moving on to perform a
lookup for the next type of record.
o If AAAA records are found, IPv6 addresses
will be included with the returned addresses.
o If A records are found, returns IPv4-mapped
IPv6 addresses and also any IPv6 addresses
that were found with the AAAA record search.
o If no A records found, returns a NULL
pointer.
AI_CANONNAME If the nodename argument is not NULL, the
function searches for the specified node's
canonical name.
Upon successful completion, the ai_canonname
member of the first addrinfo structure in the
linked list points to a null-terminated string
containing the canonical name of the specified
node name.
If the nodename argument is an address literal,
the ai_cannonname member will refer to the
nodename argument that has been converted to
its numeric binary form, in network byte order.
If the canonical name is not available, the ai_
canonname member refers to the nodename argument
or to a string with the same contents.
The ai_flags field contents are undefined.
AI_NUMERICHOST A non-NULL node name string must be a numeric
host address string.
Resolution of the service name is not performed.
AI_NUMERICSERV A non-NULL service name string must be a numeric
port string.
Resolution of the service name is not performed.
AI_PASSIVE Returns a socket address structure that your
application can use in a call to bind().
If the nodename parameter is a NULL pointer,
the IP address portion of the socket address
structure is set to INADDR_ANY (for an IPv4
address) or IN6ADDR_ANY_INIT (for an IPv6
address).
If not set, returns a socket address structure
that your application can use to call connect()
(for a connection-oriented protocol) or either
connect(), sendto(), or sendmsg() (for a
connectionless protocol). If the nodename
argument is a NULL pointer, the IP address
portion of the socket address structure is set
to the loopback address.
AI_ADDRCONFIG Used in combination with other flags, modifies
the search based on the source address or
addresses configured on the system.
You can use the flags in any combination to achieve finer control
of the translation process. Many applications use the combination
of the AI_ADDRCONFIG and AI_V4MAPPED flags to control their
search.
o If the value of ai_family is AF_INET, and an IPv4 source
address is configured on the system, getaddrinfo() searches
for A records only. If found, getaddrinfo() returns IPv4
addresses. If not, getaddrinfo() returns a NULL pointer.
o If the value of ai_family is AF_INET6 and an IPv6 source
address is configured on the system, getaddrinfo() searches
for AAAA records. If found, getaddrinfo() returns IPv6
addresses. If not, and if an IPv4 address is configured on
the system, getaddrinfo() searches for A records. If found,
getaddrinfo() returns IPv4-mapped IPv6 addresses. If not,
getaddrinfo() returns a NULL pointer.
These flags are defined in the NETDB.H header file.
addrinfo Structure Processing
Upon successful return, getaddrinfo() returns a pointer to a
linked list of one or more addrinfo structures. The application
can process each addrinfo structure in the list by following
the ai_next pointer until a NULL pointer is encountered. In each
returned addrinfo structure, the ai_family, ai_socktype, and ai_
protocol members are the corresponding arguments for a call to
the socket() function. The ai_addr member points to a filled-in
socket address structure whose length is specified by the ai_
addrlen member.
13.3 – Return Values
0 Indicates success
-1 Indicates an error
13.4 – Errors
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags parameter had an invalid value.
EAI_FAIL A nonrecoverable error occurred when
attempting to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return
value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither nodename nor servname
were supplied. At least one of these must be
supplied.
EAI_SERVICE The service passed was not recognized for the
specified socket type.
EAI_SOCKTYPE The intended socket type was not recognized.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
14 – gethostaddr
Returns the standard host address for the processor.
Format
#include <socket.h>
int gethostaddr (char *addr);
14.1 – Argument
addr
A pointer to the buffer in which the standard host address for
the current processor is returned.
14.2 – Description
This function returns the standard host address for the current
processor. The returned address is null-terminated. The addr
parameter must point to at least 16 bytes of free space.
Host addresses are limited to 16 characters.
14.3 – Return Values
0 Indicates success.
-1 Indicates that an error has occurred and is
further specified in the global errno.
15 – gethostbyaddr()
Searches the hosts database that is referenced by the TCPIP$HOST
logical name for a host record with a given IPv4 address. If the
host record is not found there, the function may also invoke the
BIND resolver to query the appropriate name server.
The $QIO equivalent is the IO$_ACPCONTROL function with the
INETACP_FUNC$C_GETHOSTBYADDR subfunction code.
Format
#include <netdb.h>
struct hostent *gethostbyaddr ( const void *addr, size_t len,
int type );
15.1 – Arguments
addr
A pointer to a series of bytes in network order specifying the
address of the host sought.
len
The number of bytes in the address pointed to by the addr
argument.
type
The type of address format being sought (AF_INET).
15.2 – Description
This function finds the first host record with the specified
address in the hosts database or using DNS/BIND.
The gethostbyaddr() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
15.3 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error; errno is set to one of the
following values.
15.4 – Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred; for example,
the server did not respond. A retry may be
successful.
16 – gethostbyname()
Searches the hosts database that is referenced by the TCPIP$HOST
logical name for a host record with the specified name or alias.
If the host record is not found, this function may also invoke
the BIND resolver to query the appropriate name server for the
information.
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 );
16.1 – Argument
name
A pointer to a null-terminated character string containing the
name or an alias of the host being sought.
16.2 – Description
This function finds the first host with the specified name or
alias in the hosts database, or using DNS/BIND.
The gethostbyname() function uses a common static area for its
return values. This means that subsequent calls to this function
overwrite previously returned host entries. You must make a copy
of the host entry if you want to save it.
16.3 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error. errno is set to one of the
following values.
16.4 – Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred; for example,
the server did not respond. A retry may be
successful.
17 – gethostent()
Retrieves an entry from the hosts database file.
Format
#include <netdb.h>
struct hostent *gethostent (void);
17.1 – Description
The gethostent() function reads the next entry of the hosts
database file (TCPIP$ETC:IPNODES.DAT).
See the NETDB.H header file for a description of the hostent
structure.
The gethostent() function uses a common static area for its
return values. Therefore, subsequent calls to gethostent()
overwrite any existing host entry. You must make a copy of the
host entry, if you wish to save it.
17.2 – Return Values
x A pointer to an object having the hostent
structure.
NULL Indicates an error; errno is set to one of the
following values.
17.3 – Errors
ENETDOWN TCP/IP Services was not started.
HOST_NOT_FOUND Host is unknown.
NO_DATA The server recognized the request and the
name, but no address is available for the
name. Another type of name server request may
be successful.
NO_RECOVERY An unexpected server failure occurred. This is
a nonrecoverable error.
TRY_AGAIN A transient error occurred; for example,
the server did not respond. A retry may be
successful.
18 – gethostname()
Returns the fully-qualified name of the local host.
Format
#include <types.h>
#include <socket.h>
int gethostname ( char *name, int namelen) ; (_DECC_V4_SOURCE)
int gethostname ( char *name, size_t namelen) ;
(not_DECC_V4_SOURCE)
18.1 – 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.
18.2 – Description
This function returns the translation of the logical names
TCPIP$INET_HOST and TCPIP$INET_DOMAIN when used with the TCP/IP
Services software.
18.3 – Return Values
0 Indicates successful completion.
-1 Indicates an error occurred. The value of
errno indicates the error.
18.4 – Errors
EFAULT The buffer described by name and namelen is
not a valid, writable part of the user address
space.
19 – getnameinfo()
Maps addresses to names in a protocol-independent way.
Format
#include <socket.h>
#include <netdb.h>
int getnameinfo ( const struct sockaddr *sa, size_t salen,
char *node, size_t nodelen, char *service,
size_t servicelen, int flags );
19.1 – Arguments
sa
Points either to a sockaddr_in structure (for IPv4) or to a
sockaddr_in6 structure (for IPv6) that holds the IP address and
port number.
salen
Specifies the length of either the sockaddr_in structure or the
sockaddr_in6 structure.
node
Points to a buffer in which to receive the null-terminated
network node name or alias corresponding to the address contained
in the sa. A NULL pointer instructs getnameinfo() to not return
a node name. The node argument and service argument must not both
be zero.
nodelen
Specifies the length of the node buffer. A value of zero
instructs getnameinfo() to not return a node name.
service
Points to a buffer in which to receive the null-terminated
network service name associated with the port number contained
in sa. A NULL pointer instructs getnameinfo() to not return a
service name. The node argument and service argument must not
both be 0.
servicelen
Specifies the length of the service buffer. A value of zero
instructs getnameinfo() to not return a service name.
flags
Specifies changes to the default actions of getnameinfo(). By
default, getnameinfo() searches for the fully-qualified domain
name of the node in the hosts database and returns it. See Flags
for a list of flags and their meanings.
19.2 – Description
This function looks up an IP address and port number in a
sockaddr structure specified by sa and returns node name and
service name text strings in the buffers pointed to by the node
and service arguments, respectively.
If the node name is not found, getnameinfo() returns the numeric
form of the node address, regardless of the value of the flags
argument. If the service name is not found, getnameinfo() returns
the numeric form of the service address (port number) regardless
of the value of the flags argument.
The application must provide buffers large enough to hold the
fully-qualified domain name and the service name, including the
terminating null characters.
Flags describes the flag bits and, if set, their meanings. The
flags are defined in the NETDB.H header file.
Table 4-2 getnameinfo() Flags
Flag Value Description
NI_DGRAM Specifies that the service is a datagram
service (SOCK_DGRAM). The default assumes
a stream service (SOCK_STREAM). This is
required for the few ports (512-514) that
have different services for UDP and TCP.
NI_NAMEREQD Returns an error if the host name cannot be
located in the hosts database.
NI_NOFQDN Searches the hosts database and returns the
node name portion of the fully-qualified
domain name for local hosts.
NI_NUMERICHOST Returns the numeric form of the host's address
instead of its name. Resolution of the host
name is not performed.
NI_NUMERICSERV Returns the numeric form (port number) of the
service address instead of its name. The host
name is not resolved.
19.3 – Return Values
0 Indicates success.
x Indicates an error occurred. The value of
errno indicates the error.
19.4 – Errors
EAI_AGAIN The name could not be resolved at this time.
Future attempts may succeed.
EAI_BADFLAGS The flags argument had an invalid value.
EAI_FAIL A nonrecoverable error occurred when
attempting to resolve the name.
EAI_FAMILY The address family was not recognized.
EAI_MEMORY There was a memory allocation failure when
trying to allocate storage for the return
value.
EAI_NONAME The name does not resolve for the supplied
parameters. Neither the node name nor the
service name were supplied. At least one of
these must be supplied.
EAI_SYSTEM A system error occurred; the error code can be
found in errno.
20 – getnetbyaddr()
Searches the network database that is referenced by the
TCPIP$NETWORK logical name for a network record with the
specified address. If the network record is not found,
this function may invoke the BIND resolver to search
TCPIP$SYSTEM:NETWORKS.DAT.
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) ;
20.1 – Arguments
net
The network number, in host byte order, of the networks database
entry required.
type
The type of network being sought (AF_INET or AF_INET6).
20.2 – Description
This function finds the first network record in the networks
database with the given address.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite any previously returned network entry.
You must make a copy of the network entry if you want to save it.
20.3 – Return Values
x A pointer to an object having the netent
structure.
NULL Indicates end of file or an error.
20.4 – Errors
EINVAL The net argument is invalid.
ESRCH The search failed.
21 – getnetbyname()
Searches the networks database for a network record with
a specified name or alias. If the network record is not
found, this function may invoke the BIND resolver to search
TCPIP$SYSTEM:NETWORKS.DAT.
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 );
21.1 – Argument
name
A pointer to a null-terminated character string containing either
the network name or an alias for the network name.
21.2 – Description
This function finds the first network record in the networks
database with the given name or alias.
The getnetbyaddr() and getnetbyname() functions use a common
static area for their return values. Subsequent calls to any of
these functions overwrite previously returned network entries.
You must make a copy of the network entry if you want to save it.
21.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to an object having the netent
structure.
21.4 – Errors
EFAULT The buffer described by name is not a valid,
writable part of the user address space.
EINVAL The name argument is invalid.
ESRCH The search failed.
22 – getnetent()
Retrieves an entry from the networks database file.
Format
#include <netdb.h>
struct netent *getnetnet (void);
22.1 – Description
This function opens and sequentially reads the networks database
file (TCPIP$SYSTEM:NETWORKS.DAT) to retrieve network information.
Returns a pointer to a netent structure that contains the
equivalent fields for a network description line in the networks
database file. The netent structure is defined in the NETDB.H
header file.
The networks database file remains open after a call by the
getservent() function. Use the endnetent() function to close the
networks database file. Use the setnetent() function to open the
networks database file and reset the file marker to the beginning
of the file.
The getnetent() function uses a common static area for its
return values, so subsequent calls to this function overwrite
any existing network entry. To save the network entry, you must
make a copy of it.
Related Functions
See also setnetent and endnetent.
22.2 – Return Values
x A pointer to a netent structure.
0 Indicates an error or end of file.
23 – getpeername()
Returns the name of the connected peer.
The $QIO equivalent is the IO$_SENSEMODE function with the p4
argument.
Format
#include <types.h>
#include <socket.h>
int getpeername ( int s, struct sockaddr *name, int *namelen
); (_DECC_V4_SOURCE)
int getpeername ( int s, struct sockaddr *name, size_t
*namelen ); (not_DECC_V4_SOURCE)
23.1 – Arguments
s
A socket descriptor created using socket().
name
A pointer to a buffer where the peer name is to be returned.
namelen
An address of an integer that specifies the size of the name
buffer. On return, it is modified to reflect the actual length,
in bytes, of the name returned.
23.2 – Description
This function returns the name of the peer connected to the
specified socket descriptor.
Related Functions
See also bind(), socket(), and getsockname().
23.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
23.4 – Errors
EBADF The descriptor is invalid.
EFAULT The name argument is not a valid part of the
user address space.
EINVAL The socket has been shut down.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The operation is not supported for the socket
protocol.
24 – getprotobyname()
Searches the protocols table until a matching protocol name is
found or until the end of the table is encountered.
Format
#include <netdb.h>
struct protoent *getprotobyname ( char *name );
24.1 – Argument
name
A pointer to a string containing the desired protocol name.
24.2 – Description
This function returns a pointer to a protoent structure
containing data from the protocols table. For information about
the protoent structure, refer to protoent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobynumber().
24.3 – Return Values
NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.
25 – getprotobynumber()
Searches the protocols table until a matching protocol number is
found or until the end of the table is encountered.
Format
#include <netdb.h>
struct protoent *getprotobynumber ( int *proto ) ;
25.1 – Argument
proto
A pointer to a string containing the desired protocol number.
25.2 – Description
This function returns a pointer to a protoent structure
containing the data from the protocols table. For information
about the protoent structure, refer to protoent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotoent() and getprotobyname().
25.3 – Return Values
NULL Indicates end of table or an error.
x A pointer to a protoent structure.
26 – getprotoent()
Reads the next entry from the protocols table.
Format
#include <netdb.h>
struct protoent *getprotoent();
26.1 – Description
This function returns a pointer to a protoent structure
containing the data from the protocols table. For information
about the protoent structure, refer to protoent Structure.
The getprotoent() function keeps an index to the table, allowing
successive calls to be used to search the entire table.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getprotobyname() and getprotobynumber().
26.2 – Return Values
NULL Indicates the end of the table or an error.
x A pointer to a protoent structure.
27 – getservbyname()
Gets information on the specified service from the services
database that is referenced by the TCPIP$SERVICE logical name.
If not found there, this function may invoke the BIND resolver to
search TCPIP$ETC:SERVICES.DAT.
Format
#include <netdb.h>
struct servent *getservbyname ( char *name, char *proto );
27.1 – Arguments
name
A pointer to a string containing the name of the service about
which information is required.
proto
A pointer to a string containing the name of the protocol (TCP or
UDP) for which to search.
27.2 – Description
This function searches the services database until a matching
service name is found or the end of file is encountered. If a
protocol name is also supplied, searches must also match the
protocol.
This function returns a pointer to a servent structure containing
the data from the network services database. For information
about the servent structure, refer to servent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyport().
27.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
28 – getservbyport()
Gets information on the specified port from the services database
that is referenced by the TCPIP$SERVICE logical name. If the
specified port is not found, this function may invoke the BIND
resolver to search TCPIP$ETC:SERVICES.DAT.
Format
#include <netdb.h>
struct servent *getservbyport ( int port, char *proto );
28.1 – Arguments
port
The port number for which to search. This port number should be
specified in network byte order. You can use the htons() function
to convert the port number to network byte order.
proto
A pointer to a string containing the name of the protocol (TCP or
UDP) for which to search.
28.2 – Description
This function searches the services database until a matching
port is found, or until end of file is encountered. If a protocol
name is also supplied, searches must also match the protocol.
This function returns a pointer to a servent structure containing
the broken-out fields of the requested line in the network
services database. For information about the servent structure,
refer to servent Structure.
All information is contained in a static area, so it must be
copied to be saved.
Related Functions
See also getservbyname().
28.3 – Return Values
NULL Indicates end of file or an error.
x A pointer to a servent structure.
28.4 – Errors
EPERM Not owner. Indicates that the wrong port
number was specified.
29 – getservent()
Retrieves an entry from the services database file.
Format
#include <netdb.h>
struct servent *getservent (void);
29.1 – Description
This function reads the next line of the services database file
(TCPIP$ETC:SERVICES.DAT).
An application program can use the getservent() function to
retrieve information about a service (such as the protocol or
the ports it uses) from the services database.
The getservent() function returns a servent structure that
contains information from the services database file. See servent
Structure for a description of the servent structure. The servent
structure is defined in the NETDB.H header file.
The ASCII text services database file remains open after a call
by the getservent() function. Use the endservent() function to
close the services database file. Use the setservent() function
to open the services database file and reset the file marker to
the beginning of the file.
The getservent function uses a common static area for its return
values, so subsequent calls to this function overwrite any
existing service entry. To save the services entry, you must
make a copy of it.
Related Functions
See also setservent and endservent.
29.2 – Return Values
x A pointer to a servent structure.
NULL Indicates an error or end of file.
30 – 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
); (_DECC_V4_SOURCE)
int getsockname ( int s, struct sockaddr *name, size_t
*namelen ); (not_DECC_V4_SOURCE)
30.1 – Arguments
s
A socket descriptor created with the 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 indicates the actual size, in
bytes, of the name returned.
30.2 – Description
This function returns the current name for the specified socket
descriptor. The name is in a format specific to the address
family assigned to the socket (AF_INET, or AF_INET6 with BSD
4.4 when _SOCKADDR_LEN is defined).
The bind() function, not the getsockname() function, makes the
association of the name to the socket.
Related Functions
See also bind() and socket().
30.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
30.4 – 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.
31 – 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,
int *optlen ); (_DECC_V4_SOURCE)
int getsockopt ( int s, int level, int optname, void *optval,
size_t *optlen ); (not_DECC_V4_SOURCE)
31.1 – 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. The IPPROTO
values are defined in the IN.H header file
(for IPv4), or the IN6.H header file (for
IPv6).
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 indicate the
actual size of the option value returned.
31.2 – Description
This function gets information on socket options. See the
appropriate protocol for information about available options
at each protocol level.
31.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
31.4 – 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.
32 – herror()
Writes a message to standard error explaining h_error.
Format
#include <netdb.h>
void herror (const char *string);
32.1 – Argument
string
A user-printable string.
32.2 – Description
This function maps the error number in the external variable h_
errno to a locale-dependent error message.
33 – hostalias()
Searches for host aliases associated with a name.
Format
#include <resolv.h>
char *hostalias (const char *name);
33.1 – Argument
name
Points to the name of the host that you want to retrieve aliases
from.
33.2 – Description
This function searches for the alias associated with the name
argument. The HOSTALIASES logical name can be used to define the
name of a file that lists the host aliases, in the form:
host alias
33.3 – Return Values
x The host alias.
NULL Indicates an error.
34 – hstrerror()
Returns an error message string.
Format
#include <string.h>
char *hstrerror (int errnum);
34.1 – Arguments
errnum
An error number specifying a value of h_errno.
34.2 – Description
This function maps the error number specified by the errnum
argument to a location-dependent error message string and returns
a pointer to the string. The string pointed to by the return
value cannot be modified by the program, but could be overwritten
by subsequent calls to this function.
34.3 – Return Values
x A pointer to the generated message string.
-1 On error, errno might be set, but no return
value is reserved to indicate an error.
34.4 – Errors
If the hstrerror() function fails, errno is
set to EINVAL, indicating the value of the
errnum argument is an invalid error number.
35 – htonl()
Converts longwords from host byte order to network byte order.
Format
#include <in.h>
unsigned long int htonl ( unsigned long int hostlong );
35.1 – Argument
hostlong
A longword in host byte order (OpenVMS systems).
35.2 – Description
This function converts 32-bit unsigned integers from host byte
order to network 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 host byte
order to network byte order.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
35.3 – Return Value
x A longword in network byte order.
36 – htons()
Converts short integers from host byte order to network byte
order.
Format
#include <in.h>
unsigned short int htons ( unsigned short int hostshort );
36.1 – 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.
36.2 – Description
This function converts 16-bit unsigned integers from host byte
order to network 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 is most often used with ports returned by the
getservent() function. To convert port numbers from OpenVMS host
byte order to network byte order, use the htons() function.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
36.3 – Return Value
x A short integer in network byte order.
Integers in network byte order cannot be used
for arithmetic computation on OpenVMS systems.
37 – if_freenameindex()
Frees dynamic memory allocated by if_nameindex() to the array of
interface names and indexes
Format
#include <if.h>
void if_freenameindex ( struct if_nameindex *ptr );
37.1 – Arguments
ptr
Points to an array of structures returned by the if_nameindex()
function.
37.2 – Description
The if_freenameindex() function frees dynamic memory allocated to
the array of interface names and indexes that the if_nameindex()
function returned.
38 – if_indextoname()
Maps an interface index to its corresponding name.
Format
#include <if.h>
char *if_indextoname ( unsigned int ifindex, char *ifname );
38.1 – Arguments
ifindex
The interface index.
ifname
Points to a buffer that is IFNAMSIZ bytes in length. (IFNAMSIZ is
defined in the IF.H header file.) If an interface name is found,
it is returned in the buffer.
38.2 – Description
This function maps an interface index to its corresponding name.
38.3 – Return Values
Interface name If interface name is found, it is returned to
the buffer.
NULL If no interface name corresponds to the
specified index, the function returns NULL
and sets errno to ENXIO.
38.4 – Errors
ENXIO No interface name corresponds to the specified
index.
System error A system error.
39 – if_nameindex()
Returns an array of all interface names and indexes.
Format
#include <if.h>
struct if_nameindex *if_nameindex ( void );
39.1 – Description
This function dynamically allocates memory for an array of
if_nameindex structures, one structure for each interface. A
structure with an if_index value of 0 and a NULL if_name value
indicates the end of the array.
The following if_nameindex structure must also be defined
by including the IF.H header file prior to the call to if_
nameindex():
struct if_nameindex {
unsigned int if_index;
char *if_name;
};
To free the memory allocated by this function, use the if_
freenameindex() function. If an error occurs, the function
returns a NULL pointer and sets errno to an appropriate value.
39.2 – Return Values
NULL Indicates an error; errno is set to an
appropriate value.
40 – if_nametoindex()
Maps an interface name to its corresponding index.
Format
#include <if.h>
unsigned int if_nametoindex ( const char *ifname );
40.1 – Arguments
ifname
Points to a buffer that contains the interface name.
40.2 – Description
This function maps an interface name to its corresponding
interface index number.
40.3 – Return Values
0 (zero) Interface does not exist.
x Upon successful conversion, the if_
nametoindex() function returns an interface
index number.
41 – inet6_opt_append()
Returns the length of an IPv6 extension header with a new option
and appends the option.
Format
#include <in6.h>
int inet6_opt_append ( void *extbuf, size_t extlen, int
offset, uint8_t type, size_t len, uint_t
align, void **databufp );
41.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to initialize. Valid
values are 0 if extbuf equals 0, a value returned by inet6_opt_
finish(), or any number that is a multiple of 8.
offset
Specifies the length of the existing extension header. Obtain
this value from a prior call to inet6_opt_init() or inet6_opt_
append().
type
Specifies the type of option. Specify a value from 2 to 255,
inclusive, excluding 194.
len
Specifies the length of the option data, excluding the option
type and option length fields. Specify a value from 0 to 255,
inclusive.
align
Specifies the alignment of the option. Specify one of the
following values: 1, 2, 4, or 8.
databufp
Points to a buffer that contains the option data.
41.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the updated number of bytes in an extension
header.
If you specify extbuf as a valid pointer and valid extlen and
align arguments, the function returns the same information as in
the previous case, but also inserts the pad option, initializes
the type and len fields, and returns a pointer to the location
for the option content.
After you call inet6_opt_append(), you can then use the data
buffer directly or call inet6_opt_set_val() to specify the option
contents.
41.3 – Return Values
x Upon successful completion, the inet6_opt_
append() function returns the updated number
of bytes in an extension header.
-1 Failure
41.4 – Errors
EBADF The socket descriptor is invalid.
ECONNABORTED A connection has been aborted.
EFAULT The addr argument is not in a writable part of
the user address space.
EINTR The accept() function was interrupted by a
signal before a valid connection arrived.
EINVAL The socket is not accepting connections.
EMFILE There are too many open file descriptors.
ENFILE The maximum number of file descriptors in the
system is already open.
ENETDOWN TCP/IP Services was not started.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The reference socket is not of type SOCK_
STREAM.
EPROTO A protocol error occurred.
EWOULDBLOCK The socket is marked nonblocking, and no
connections are present to be accepted.
42 – inet6_opt_find()
Finds a specific option in an extension header.
Format
#include <in6.h>
int inet6_opt_find ( void *extbuf, size_t extlen, int offset,
uint8_t type, size_t *lenp, void **databufp
);
42.1 – Arguments
extbuf
Points to a buffer that contains an extension header.
extlen
Specifies the length, in bytes, of the extension header.
offset
Specifies the location in the extension header of an option.
Valid values are either 0 (zero) for the first option or the
length returned from a previous call to either inet6_opt_next()
or inet6_opt_find().
type
Specifies the type of option to find.
lenp
Points to the length of the option found.
databufp
Points to the option data.
42.2 – Description
This function searches a received option extension header for an
option specified by type. If it finds the specified option, it
returns the option length and a pointer to the option data. It
also returns an offset to the next option, which you can specify
in the offset argument to subsequent calls to inet6_opt_next()
in order to search for additional occurrences of the same option
type.
42.3 – Return Values
x Upon successful completion, the inet6_opt_
find() function returns an offset from which
you can begin the next search in the data
buffer.
-1 Failure
43 – inet6_opt_finish()
Returns the total length of an IPv6 extension header, including
padding, and initializes the option.
Format
#include <in6.h>
int inet6_opt_finish ( void *extbuf, size_t extlen, int offset
);
43.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to finish
initializing. A valid value is any number greater than or equal
to 0.
offset
Specifies the length of the existing extension header. Obtain
this value from a prior call to inet6_opt_init() or inet6_opt_
append().
43.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the total number of bytes in an extension
header, including final padding.
If you specify extbuf as a valid pointer and a valid extlen
argument, the function returns the same information as in the
previous case, increments the buffer pointer, and verifies that
the buffer is large enough to hold the header.
43.3 – Return Values
x Upon successful completion, the inet6_opt_
finish() function returns the total number
of bytes in an extension header, including
padding.
-1 Failure
44 – inet6_opt_get_val()
Extracts data items from the data portion of an IPv6 option.
Format
#include <in6.h>
int inet6_opt_get_val ( void *databuf, size_t offset, void
*val, int vallen );
44.1 – Arguments
databuf
Points to a buffer that contains an extension header. This is
a pointer returned by a call to inet6_opt_find() or inet6_opt_
next().
offset
Specifies the location in the data portion of the option from
which to extract the data. You can access the first byte after
the option type and length by specifying the offset of 0.
val
Points to a destination for the extracted data.
vallen
Specifies the length of the data, in bytes, to be extracted.
44.2 – Description
This function copies data items from data buffer databuf
beginning at offset to the location val. In addition, it returns
the offset for the next data field to assist you in extracting
option content that has multiple fields.
Make sure that each field is aligned on its natural boundaries.
44.3 – Return Values
x Upon successful completion, the inet6_opt_get_
val() function returns the offset for the next
field in the data buffer.
-1 Failure
45 – inet6_opt_init()
Returns the length of an IPv6 extension header with no options
and initializes the header.
Format
#include <in6.h>
int inet6_opt_init ( void *extbuf, size_t extlen );
45.1 – Arguments
extbuf
Points to a buffer that contains an extension header. This is
either a valid pointer or a NULL pointer.
extlen
Specifies the length of the extension header to initialize. Valid
values are 0 and any number that is a multiple of 8.
45.2 – Description
This function, when called with extbuf as a NULL pointer and
extlen as 0, returns the number of bytes in an extension header
that has no options.
If you specify extbuf as a valid pointer and extlen as a
number that is a multiple of 8, the function returns the same
information as in the previous case, initializes the extension
header, and sets the length field.
45.3 – Return Values
x Upon successful completion, the inet6_opt_
init() function returns the number of bytes in
an extension header with no options.
-1 Failure
46 – inet6_opt_next()
Parses received option extension headers.
Format
#include <in6.h>
int inet6_opt_next ( void *extbuf, size_t extlen, int
offset, uint8_t *typep, size_t *lenp, void
**databufp );
46.1 – Arguments
extbuf
Points to a buffer that contains an extension header.
extlen
Specifies the length, in bytes, of the extension header.
offset
Specifies the location in the extension header of an option.
Valid values are either 0 for the first option or the length
returned from a previous call to either inet6_opt_next() or
inet6_opt_find().
typep
Points to the type of the option found.
lenp
Points to the length of the option found.
databufp
Points to the option data.
46.2 – Description
This function parses a received option extension header and
returns the next option. In addition, it returns an offset to
the next option that you specify in the offset parameter to
subsequent calls to inet6_opt_next().
This function does not return any PAD1 or PADN options.
46.3 – Return Values
x Upon successful completion, the inet6_opt_
next() function returns the offset for the
next option in the data buffer.
-1 Failure
47 – inet6_opt_set_val()
Adds one component of the option content to the options header.
Format
#include <in6.h>
int inet6_opt_set_val ( void *databuf, size_t offset, void
*val int vallen );
47.1 – Arguments
databuf
Points to a buffer that contains an extension header. This is a
pointer returned by a call to inet6_opt_append().
offset
Specifies the location in the data portion of the option into
which to insert the data. You can access the first byte after the
option type and length by specifying the offset of 0 (zero).
val
Points to the data to be inserted.
vallen
Specifies the length of the data, in bytes, to be inserted.
47.2 – Description
This function copies data items at the location val into a data
buffer databuf beginning at offset. In addition, it returns the
offset for the next data field to assist you in composing content
that has multiple fields.
Make sure that each field is aligned on its natural boundaries.
47.3 – Return Values
x Upon successful completion, the inet6_opt_set_
val() function returns the offset for the next
field in the data buffer.
-1 Failure
48 – inet6_rth_add()
Adds an IPv6 address to the routing header under construction.
Format
#include <in6.h>
int inet6_rth_add ( void *bp, const struct in6_addr *addr );
48.1 – Arguments
bp
Points to a buffer that is to contain an IPv6 routing header.
addr
Points to an IPv6 address to add to the routing header.
48.2 – Description
This function adds an IPv6 address to the end of the routing
header under construction. The address pointed to by addr cannot
be an IPv6 V4-mapped address or an IPv6 multicast address.
The function increments the ip6r0_segleft member in the ip6_
rthdr0 structure. The ip6_rthdr0 structure is defined in the
IP6.H header file.
Only routing header type 0 is supported.
48.3 – Return Values
x Upon successful completion, the inet6_rth_
add() function returns 0 (zero).
-1 Failure
49 – inet6_rth_getaddr()
Retrieves an address for an index from an IPv6 routing header.
Format
#include <in6.h>
struct in6_addr *inet6_rth_getaddr ( const void *bp, int index
);
49.1 – Arguments
bp
Points to a buffer that contains an IPv6 routing header.
index
Specifies a value that identifies a position in a routing header
for a specific address. Valid values range from 0 to the return
value from inet6_rth_segments() minus 1.
49.2 – Description
This function uses a specified index value and retrieves a
pointer to an address in a routing header specified by bp. Call
inet6_rth_segments() before calling this function in order to
determine the number of segments (addresses) in the routing
header.
49.3 – Return Values
x Upon successful completion, the inet6_rth_
getaddr() function returns a pointer to an
address.
NULL pointer Failure
50 – inet6_rth_init()
Initializes an IPv6 routing header buffer.
Format
#include <in6.h>
void *inet6_rth_init ( void *bp, int bp_len, int type, int
segments );
50.1 – Arguments
bp
Points to a buffer that is to contain an IPv6 routing header.
bp_len
Specifies the length, in bytes, of the buffer.
type
Specifies the type of routing header. The valid value is IPV6_
RTHDR_TYPE_0 for IPv6 routing header type 0.
segments
Specifies the number of segments or addresses that are to be
included in the routing header. The valid value is from 0 to 127,
inclusive.
50.2 – Description
This function initializes a buffer and buffer data for an IPv6
routing header. The function sets the ip6r0_segleft, ip6r0_nxt,
and ip6r0_reserved members in the ip6_rthdr0 structure to zero.
In addition, it sets the ip6r0_type member to type and sets the
ip6r0_len member based on the segments argument. The ip6_rthdr0
structure is defined in the IP6.H header file.
The application must allocate the buffer. Use the inet6_rth_
space() function to determine the buffer size.
Use the returned pointer as the first argument to the inet6_rth_
add() function.
50.3 – Return Values
x Upon successful completion, the inet6_rth_
init() function returns a pointer to the
buffer that is to contain the routing header.
NULL pointer Failure. If the type is not supported, the bp
is a null, or the number of bp_len is invalid.
51 – inet6_rth_reverse()
Reverses the order of addresses in an IPv6 routing header.
Format
#include <in6.h>
int inet6_rth_reverse ( const void *in, void *out );
51.1 – Arguments
in
Points to a buffer that contains an IPv6 routing header.
out
Points to a buffer that is to contain the routing header with the
reversed addresses. This parameter can point to the same buffer
specified by the in parameter.
51.2 – Description
This function reads an IPv6 routing header and writes a new
routing header, reversing the order of addresses in the new
header. The in and out parameters can point to the same buffer.
The function sets the ip6r0_segleft member in the ip6_rthdr0
structure to the number of segments (addresses) in the new
header.
The ip6_rthdr0 structure is defined in the IP6.H header file.
51.3 – Return Values
0 (zero) Success
-1 Failure
52 – inet6_rth_segments()
Returns the number of segments (addresses) in an IPv6 routing
header.
Format
#include <in6.h>
int inet6_rth_segments ( const void *bp );
52.1 – Arguments
bp
Points to a buffer that contains an IPv6 routing header.
52.2 – Description
This function returns the number of segments (or addresses) in an
IPv6 routing header.
52.3 – Return Values
x Upon successful completion, the inet6_rth_
segments() function returns the number of
segments, 0 (zero) or greater than 0.
-1 Failure
53 – inet6_rth_space()
Returns the number of bytes required for an IPv6 routing header.
Format
#include <in6.h>
size_t inet6_rth_space ( int type, int segments );
53.1 – Arguments
type
Specifies the type of routing header. The valid value is IPV6_
RTHDR_TYPE_0 for IPv6 routing header type 0.
segments
Specifies the number of segments or addresses that are to be
included in the routing header. The valid value is from 0 to 127,
inclusive.
53.2 – Description
This function determines the amount of space, in bytes, required
for a routing header. Although the function returns the amount of
space required, it does not allocate buffer space. This enables
the application to allocate a larger buffer.
If the application uses ancillary data, it must pass the returned
length to CMSG_LEN() to determine the amount of memory required
for the ancillary data object, including the cmsghdr structure.
NOTE
If an application wants to send other ancillary data
objects, it must specify them to sendmsg() as a single msg_
control buffer.
53.3 – Return Values
x Upon successful completion, the inet6_rth_
space() function returns the length, in bytes,
of the routing header and the specified number
of segments.
0 (zero) Failure, if the type is not supported or the
number of segments is invalid for the type of
routing header.
54 – inet_aton()
Converts an IP address in the standard dotted-decimal format
to its numeric binary form, in network byte order. Replaces the
inet_addr() function.
Format
#include <inet.h>
int inet_aton ( const char *cp, struct in_addr *in);
54.1 – Argument
cp
A pointer to a null-terminated character string containing an
internet address in the standard internet dotted-decimal format.
in
A pointer to a buffer that is to contain the numeric internet
address in network byte order.
54.2 – Description
This function returns a numeric internet address in network byte
order that represents the internet address supplied in 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 and I64 systems has
zero-extended bits in the high 32 bits of R0.
54.3 – Return Value
1 Indicates success.
0 Indicates failure.
55 – inet_lnaof()
Returns the local network address portion of an IP address.
Format
#include <in.h>
#include <inet.h>
int inet_lnaof ( struct in_addr in );
55.1 – Argument
in
An IP address.
55.2 – Description
This function returns the local network address 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.
55.3 – Return Value
x The local network address portion of an IP
address, in host byte order.
56 – inet_makeaddr()
Returns an IP 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 );
56.1 – Arguments
net
An IP network address in host byte order.
lna
A local network address on network net in host byte order.
56.2 – Description
This function combines the net and lna arguments into a single IP
address.
NOTE
The 64-bit return from OpenVMS Alpha and I64 systems has
zero-extended bits in the high 32 bits of R0.
56.3 – Return Value
x An IP address in network byte order.
57 – 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 );
57.1 – Argument
in
An IP address.
57.2 – 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.
57.3 – Return Value
x The internet network portion of an IP address,
in host byte order.
58 – 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 );
58.1 – Argument
cp
A pointer to an ASCII (null-terminated) character string
containing a network address in the dotted-decimal format.
58.2 – 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.
58.3 – Return Values
-1 Indicates that cp does not point to a proper
internet network address.
x An internet network address, in local host
order.
59 – 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 );
59.1 – Argument
in
An IP address in network byte order.
59.2 – 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.
59.3 – Return Value
x A pointer to a string containing the IP
address in dotted-decimal format.
60 – 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 );
60.1 – 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.
60.2 – Description
This function converts a numeric IP address value to a text
string.
60.3 – Return Values
Pointer to the Success
buffer containing
the text string
Pointer to the Failure
buffer containing
NULL
61 – 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 );
61.1 – 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.
61.2 – Description
This function converts a text string to a numeric value in
network byte order.
o 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.
o 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.
o 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.
61.3 – 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.
61.4 – Errors
EAFNOSUPPORT The address family specified in the af
parameter is unknown.
62 – ioctl()
Controls I/O requests to obtain network information.
Format
#include <ioctl.h>
int ioctl ( int s, int request, ... /* arg */ );
62.1 – 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:
o Socket operations
o File operations
o Interface operations
o ARP cache operations
o Routing table operations
Refer to IOCTL Requests 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.
62.2 – 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.
62.3 – Return Values
-1 Error; errno is set to indicate the error.
62.4 – 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.
63 – 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 );
63.1 – 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.
63.2 – 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().
63.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
63.4 – 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().
64 – ntohl()
Converts longwords from network byte order to host byte order.
Format
#include <in.h>
unsigned long ntohl ( unsigned long netlong );
64.1 – Argument
netlong
A longword in network byte order. Integers in network byte order
cannot be used for arithmetic computation on OpenVMS systems.
64.2 – 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.
64.3 – Return Value
x A longword in host byte order.
65 – ntohs()
Converts short integers from network byte order to host byte
order.
Format
#include <in.h>
unsigned short ntohs ( unsigned short netshort );
65.1 – Argument
netshort
A short integer in network byte order. Integers in network
byte order cannot be used for arithmetic computation on OpenVMS
systems.
65.2 – 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.
65.3 – Return Value
x A short integer in host byte order (OpenVMS
systems).
66 – poll()
Monitors conditions on multiple file descriptors.
Format
#include <poll.h>
int poll (struct pollfd fds[], nfds_t nfds, int timeout);
66.1 – 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.
66.2 – 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:
o POLLIN
Normal data may be received without blocking.
o POLLRDNORM
Same as POLLIN.
o POLLRDBAND
Out-of-band data may be received without blocking.
o POLLPRI
Same as POLLRDBAND
o POLLOUT
Normal data may be written without blocking.
o POLLWRNORM
Same as POLLOUT.
o 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.
66.3 – 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.
66.4 – Errors
EAGAIN The allocation of internal data structures
failed but a subsequent request may succeed.
EINTR A signal was caught during the poll()
function.
67 – 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 );
67.1 – 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.
67.2 – 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().
67.3 – 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.
67.4 – 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.
68 – 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 );
(_DECC_V4_SOURCE)
size_t recv ( int s, void *buf, ssize_t len, int flags );
(not_DECC_V4_SOURCE)
68.1 – 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 of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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()
functions to send out-of-band data.
MSG_PEEK Allows you to examine data in the receive
buffer without removing it from the system's
buffers.
68.2 – Description
This function receives data from a connected socket. To receive
data on an unconnected socket, use the recvfrom() or recvmsg()
functions. The received data is placed in the buffer buf.
Data is sent by the socket's peer using the send, sendmsg(),
sendto(), or write() functions.
Use the select() function to determine when more data arrives.
If no data is available at the socket, the recv() call waits for
data to arrive, unless the socket is nonblocking. If the socket
is nonblocking, a -1 is returned with the external variable errno
set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
68.3 – Return Values
x The number of bytes received and placed in
buf.
0 Peer has closed its send side of the
connection.
-1 Error; errno is set to indicate the error.
68.4 – 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 recv() 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.
69 – 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) ;
(_DECC_V4_SOURCE)
ssize_t recvfrom ( int s, void *buf, size_t len, int flags,
struct sockaddr *from, size_t *fromlen) ;
(not_DECC_V4_SOURCE)
69.1 – Arguments
s
A socket descriptor created with the socket() function and
bound to a name using the bind() function or as a result of the
accept() function.
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 of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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()
functions.
MSG_PEEK Allows you to examine the data that is next in
line to be received without actually removing
it from the system's buffers.
from
A buffer that the recvfrom() function uses to place the address
of the sender who sent the data.
If from is non-null, the address is returned. If from is null,
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.
69.2 – Description
This function 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.
To receive bytes from any source, the socket does not need to be
connected.
You can use the select() function 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. If
the socket is nonblocking, a -1 is returned with the external
variable errno set to EWOULDBLOCK.
Related Functions
See also read(), send(), sendmsg(), sendto(), and socket().
69.3 – 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.
69.4 – Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT A valid message buffer was not specified.
Nonexistent or protected address space is
specified for the message buffer.
EINTR A signal interrupted the recvfrom() 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.
ETIMEDOUT The connection timed out when trying to
establish a connection or when a transmission
timed out on an active connection.
EWOULDBLOCK The NBIO (nonblocking) flag is set for the
socket descriptor and the process delayed
during the write operation.
70 – 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)
70.1 – Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a msghdr structure for receiving the data.
flags
A bit mask that can contain one or more of the following
flags. The mask is built by using a logical OR operation on the
appropriate values.
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() functions 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.
70.2 – Description
You can use this function with any socket, whether or not it
is in a connected state. 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 does not need to be connected to
another socket.
When the ioveciovcnt array specifies more than one buffer, the
input data is scattered into iovcnt buffers as specified by the
members of the iovec array:
iov0, iov1, ..., ioviovcnt
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() function to determine when more data
arrives.
Related Functions
See also read(), send(), and socket().
70.3 – 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.
70.4 – Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EFAULT The message argument is not in a readable or
writable part of user address space.
EINTR This function was interrupted by a signal
before any data was available.
EINVAL The MSG_OOB flag is set, and no out-of-band
data is available.
The value of the msg_iovlen member of the
msghdr structure is less than or equal to zero
or is greater than IOV_MAX.
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.
EWOULDBLOCK The socket is marked nonblocking, and no data
is ready to be received.
71 – select()
Allows you to poll or check a group of sockets for I/O activity.
This function indicates which sockets are ready to be read or
written, or which sockets have an exception pending.
Format
#include <time.h>
int select ( int nfds, int *readfds, int *writefds,
int *execptfds, struct timeval *timeout );
(_DECC_V4_SOURCE)
int select ( int nfds, fd_set *readfds, fd_set *writefds,
int *execptfds, struct timeval *timeout );
(not_DECC_V4_SOURCE)
71.1 – Arguments
nfds
The number of open objects that may be ready for reading or
writing or that have exceptions pending. The nfds argument is
normally limited to FD_SETSIZE, which is defined in the SOCKET.H
header file. Note that a single process can have a maximum of
65535 simultaneous channels (including sockets) on OpenVMS Alpha
and I64 systems, and a maximum of 2047 on OpenVMS VAX systems.
readfds
A pointer to an array of bits, organized as integers, that should
be examined for read readiness. If bit n of the longword is set,
socket descriptor n is checked to see whether it is ready to be
read. All bits set in the bit mask must correspond to the file
descriptors of sockets. The select() function cannot be used on
normal files.
On return, the array to which readfds points contains a bit mask
of the sockets that are ready for reading. Only bits that were
set on entry to the select() function can be set on exit.
writefds
A pointer to an array of bits, organized as integers, that should
be examined for write readiness. If bit n of the longword is
set, socket descriptor n is checked to see whether it is ready
to be written to. All bits set in the bit mask must correspond to
socket descriptors.
On return, the array to which writefds points contains a bit mask
of the sockets that are ready for writing. Only bits that were
set on entry to the select() function are set on exit.
exceptfds
A pointer to an array of bits, organized as integers, that
is examined for exceptions. If bit n of the longword is set,
socket descriptor n is checked to see whether it has any pending
exceptions. All bits set in the bit mask must correspond to the
file descriptors of sockets.
On return, the array exceptfds pointer contains a bit mask of the
sockets that have exceptions pending. Only bits that were set on
entry to the select() function can be set on exit.
timeout
The length of time that the select() function should examine the
sockets before returning. If one of the sockets specified in the
readfds, writefds, and exceptfds bit masks is ready for I/O, the
select() function returns before the timeout period expires.
The timeout argument points to a timeval structure.
71.2 – Description
This function determines the I/O status of the sockets specified
in the various mask arguments. It returns when a socket is ready
to be read or written, when the timeout period expires, or when
exceptions occur. If timeout is a non-null pointer, it specifies
a maximum interval to wait for the selection to complete.
If the timeout argument is null, the select() function blocks
indefinitely until a selected event occurs. To effect a poll,
the value for timeout should be non-null, and should point to a
zero-value structure.
If a process is blocked on a select() function while waiting for
input for a socket and the sending process closes the socket,
then the select() function notes this as an event and unblocks
the process. The descriptors are always modified on return if the
select() function returns because of the timeout.
NOTE
When the socket option SO_OOBINLINE is set on the device
socket, the select() function on both read and exception
events returns the socket mask that is set on both the read
and the exception mask. Otherwise, only the exception mask
is set.
Related Functions
See also accept(), connect(), read(), recv(), recvfrom(),
recvmsg(), send(), sendmsg(), sendto(), and write().
71.3 – Return Values
n The number of sockets ready for I/O or pending
exceptions. This value matches the number
of returned bits that are set in all output
masks.
0 The select() function timed out before any
socket became ready for I/O.
-1 Error; errno is set to indicate the error.
71.4 – Errors
EBADF One or more of the I/O descriptor sets
specified an invalid file descriptor.
EINTR A signal was delivered before the time limit
specified by the timeout argument expired and
before any of the selected events occurred.
EINVAL The time limit specified by the timeout
argument is invalid.
The nfds argument is less than zero, or
greater than or equal to FD_SETSIZE.
EAGAIN Allocation of internal data structures failed.
A later call to the select() function may
complete successfully.
ENETDOWN TCP/IP Services was not started.
ENOTSOCK The socket descriptor is invalid.
72 – send()
Sends bytes through a socket to its connected peer.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <types.h>
#include <socket.h>
int send ( int s, char *msg, int len, int flags );
(_DECC_V4_SOURCE)
ssize_t send ( int s, const void *msg, size_t len, int flags
); (not_DECC_V4_SOURCE)
72.1 – Arguments
s
A socket descriptor created with the socket() function that was
connected to another socket using the accept() or connect()
function.
msg
A pointer to a buffer containing the data to be sent.
len
The length, in bytes, of the data pointed to by msg.
flags
Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver also specifies MSG_OOB in
the flag argument of its recv() or recvfrom() call.
72.2 – Description
This function sends data to a connected peer.
You can use this function only on connected sockets. To send
data on an unconnected socket, use the sendmsg() or sendto()
function. The send() function passes data along to its connected
peer, which can receive the data by using the recv() or read()
function.
Normally the send() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the send() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, send() fails with the EMSGSIZE error.
If the address specified is an INADDR_BROADCAST address, then
the SO_BROADCAST socket option must have been set and the process
must have SYSPRV or BYPASS privilege for the I/O operation to
succeed.
A success return from the send() does not guarantee that the data
has been received by the peer. All errors (except EWOULDBLOCK)
are detected locally. To determine when it is possible to send
more data, use the select() function.
Related Functions
See also read(), recv(), recvmsg(), recvfrom(), getsockopt(),
and socket().
72.3 – Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
72.4 – Errors
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ The socket is not connection-oriented, and no
peer address is set.
EFAULT The message argument is not in a readable or
writable part of the user address space.
EINTR A signal interrupted the send() before any
data was transmitted.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The socket is not connected or has not had the
peer prespecified.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
EWOULDBLOCK The socket is marked nonblocking, and no space
is available for the send() function.
73 – sendmsg()
Sends gathered bytes through a socket to any other socket.
Format
#include <types.h>
#include <socket.h>
int sendmsg ( int s, struct msghdr *msg, int flags ); (BSD
Version 4.4)
int sendmsg ( int s, struct omsghdr *msg, int flags ); (BSD
Version 4.3)
73.1 – Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a msghdr structure containing the message to be
sent.
The msg_iov field of the msghdr structure is used as a series of
buffers from which data is read in order until msg_iovlen bytes
have been obtained.
flags
Can be either 0 or MSG_OOB. If it is equal to MSG_OOB, the data
is sent out of band. Data can be received before other pending
data on the receiving socket if the receiver specifies a flag of
MSG_OOB.
73.2 – Description
This function sends the data in a msghdr structure to any other
socket.
You can use this function on any socket to send data to any named
socket. The data in the msg_iov field of the msghdr structure
is sent to the socket whose address is specified in the msg_name
field of the structure. The receiving socket gets the data using
the read(), recv(), recvfrom(), or recvmsg() function. When the
iovec array specifies more than one buffer, the data is gathered
from all specified buffers before being sent.
Normally the sendmsg() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the sendmsg() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, sendmsg() fails with the EMSGSIZE error.
If the address specified is an INADDR_BROADCAST address, the
SO_BROADCAST socket option must be set and the process must
have OPER, SYSPRV, or BYPASS privilege for the I/O operation
to succeed.
A success return from sendmsg() does not guarantee that the data
has been received by the peer. All errors (except EWOULDBLOCK)
are detected locally. To determine when it is possible to send
more data, use the select() function.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
73.3 – Return Values
n The number of bytes sent.
-1 Error; errno is set to indicate the error.
73.4 – Errors
ENOTSOCK The socket descriptor is invalid.
EFAULT An invalid user space address is specified for
an argument.
EMSGSIZE The socket requires that messages be sent
atomically, but 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.
74 – 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 ); (_DECC_V4_SOURCE)
ssize_t sendto ( int s, const void *msg, size_t len, int
flags, const struct sockaddr *to, size_t tolen
); (not_DECC_V4_SOURCE)
74.1 – Arguments
s
A socket descriptor created with the socket() function.
msg
A pointer to a buffer containing the data to be sent.
len
The length of the data pointed to by the msg argument.
flags
Can be either 0 or MSG_OOB. If it is MSG_OOB, the data is sent
out of band. Data can be received before other pending data on
the receiving socket if the receiver specifies MSG_OOB in the
flag argument of its recv(), recvfrom() or recvmsg() call.
to
Points to the address structure of the socket to which the data
is to be sent.
tolen
The length of the address pointed to by the to argument.
74.2 – Description
This function 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 the read(), recv(), recvfrom(), or
recvmsg() function.
Normally the sendto() function blocks if there is no space for
the incoming data in the buffer. It waits until the buffer space
becomes available. If the socket is set to nonblocking and there
is no space for the data, the sendto() function fails with the
EWOULDBLOCK error.
If the message is too large to be sent in one piece, and the
socket type is SOCK_DGRAM, which requires that messages be sent
in one piece, sendto() fails with the EMSGSIZE error.
If the address specified is a INADDR_BROADCAST address, then the
SO_BROADCAST socket option must have been set and the process
must have SYSPRV or BYPASS privilege for the I/O operation to
succeed.
A success return from the sendto() does not guarantee that
the data has been received by the peer. All errors (except
EWOULDBLOCK) are detected locally. To determine when it is
possible to send more data, use the select() function.
Related Functions
See also read(), recv(), recvfrom(), recvmsg(), socket(), and
getsockopt().
74.3 – Return Values
n The number of bytes sent. This value normally
equals len.
-1 Error; errno is set to indicate the error.
74.4 – Errors
EAFNOSUPPORT Addresses in the specified address family
cannot be used with this socket.
EBADF The socket descriptor is invalid.
ECONNRESET A connection was forcibly closed by a peer.
EDESTADDRREQ You did not specify a destination address for
the connectionless socket and no peer address
is set.
EFAULT An invalid user space address is specified for
an argument.
EHOSTUNREACH The destination host is unreachable.
EINTR A signal interrupted sendto() before any data
was transmitted.
EINVAL The tolen argument is not a valid size for the
specified address family.
EISCONN The connection-oriented socket for which a
destination address was specified is already
connected.
EMSGSIZE The message is too large to be sent all at
once, as the socket requires.
ENETDOWN The local network connection is not
operational.
ENETUNREACH The destination network is unreachable.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system did not have sufficient memory to
fulfill the request.
ENOTCONN The socket is connection-oriented but is not
connected.
ENOTSOCK The socket descriptor is invalid.
EOPNOTSUPP The socket argument is associated with a
socket that does not support one or more of
the values set in flags.
EPIPE The socket is shut down for writing or is
connection oriented, and the peer is closed or
shut down for reading. In the latter case, if
the socket is of type SOCK_STREAM, the SIGPIPE
signal is generated to the calling process.
EWOULDBLOCK The socket is marked nonblocking, and no space
is available for the sendto() function.
75 – sethostent()
Opens the hosts database file.
Format
#include <netdb.h>
void sethostent (int stay_open);
75.1 – Argument
stay_open
Specifies a value used to indicate when to close the hosts
database file (TCPIP$ETC:IPNODES.DAT):
o A value of 0 closes the hosts database file after each call
to the gethostbyname(), gethostbyaddr(), or gethostent()
function.
o A nonzero value keeps the hosts database file open after each
call.
75.2 – Description
This function opens the hosts database file and resets the file
marker to the beginning of the file.
Passing a nonzero value to the stay_open argument keeps the
connection open until the endhostent() or exit() function is
called.
Related Functions
See also endhostent().
76 – setnetent()
Opens the networks database file.
Format
#include <netdb.h>
void setnetent (int stay_open);
76.1 – Argument
stay_open
Specifies a value used to indicate when to close the networks
database file (TCPIP$SYSTEM:NETWORKS.DAT):
o A value of 0 closes the networks database file after each call
to the getnetent() function.
o A nonzero value keeps the networks database file open after
each call.
76.2 – Description
This function opens the networks database file and resets the
file marker to the beginning of the file.
Passing a nonzero stay_open argument keeps the connection open
until you call the endnetent() or exit() function.
Related Functions
See also endnetent(), getnetent(), and exit().
77 – setprotoent()
Sets the state of the protocols table.
Format
#include <netdb.h>
void setprotoent (int stay_open);
77.1 – Argument
stay_open
Specifies a value used to indicate when to reset the protocols
table index:
o A value of 0 resets the protocols table index after each call
to the getprotoent function.
o A nonzero value does not reset the protocols table index after
each call.
77.2 – Description
This function sets the index marker to the beginning of the
protocols table.
Passing a nonzero stay_open argument will allow the index to
advance until you call the endprotoent() or exit() function.
Related Functions
See also endprotoent(), exit(), and getprotoent().
77.3 – Return Values
1 Indicates success.
0 Indicates an error; unable to access the
protocols table.
78 – setservent()
Opens the services database file.
Format
#include <netdb.h>
void setservent (int stay_open);
78.1 – Argument
stay_open
Specifies a value used to indicate when to close the services
database file (TCPIP$ETC:SERVICES.DAT):
o A value of 0 closes the services database file after each call
to the setservent() function.
o A nonzero value keeps the services database file open after
each call to setservent().
78.2 – Description
This function opens the services database file and resets the
file marker to the beginning of the file.
Passing a nonzero stay_open argument keeps the connection
open until you call the endservent() function or the exit()
function.
Related Functions
See also endservent(), exit(), and getservent().
79 – setsockopt()
Sets options on a socket.
The $QIO equivalent is the IO$_SETMODE function.
Format
#include <types.h>
#include <socket.h>
int setsockopt ( int s, int level, int optname, char *optval,
int optlen ); (_DECC_V4_SOURCE)
int setsockopt ( int s, int level, int optname, const void
*optval, size_t optlen ); (not_DECC_V4_SOURCE)
79.1 – Arguments
s
A socket descriptor created by the socket() function.
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. For IPv4, see the IN.H
header file for the IPPROTO values. For IPv6,
see the IN6.H header file for the IPPROTO_IPV6
values.
optname
Interpreted by the protocol specified in level. Options at each
protocol level are documented with the protocol.
Refer to:
o Socket Options for a list of socket options
o TCP Protocol Options for a list of TCP options
o IP Protocol Options for a list of IP options
optval
Points to a buffer containing the arguments 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 argument defined in the
SOCKET.H header 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.
If the socket is type SOCK_STREAM, which promises the 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 soon as possible.
optlen
An integer specifying the size of the buffer pointed to by
optval.
79.2 – Description
This function 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 the value of 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
value for the level argument to the protocol number (IPPROTO_TCP)
of TCP.
For IPv4, see the IN.H header file for the various IPPROTO
values. For IPv6, see the IN6.H header file for the various
IPPROTO_IPV6 values.
79.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
79.4 – Errors
EACCES The calling process does not have appropriate
permissions.
EBADF The descriptor is invalid.
EDOM The send and receive timeout values are too
large to fit in the timeout fields of the
socket structure.
EINVAL The optlen argument is invalid.
EISCONN The socket is already connected; the specified
option cannot be set when the socket is in the
connected state.
EFAULT The optval argument is not in a readable part
of the user address space.
ENOBUFS The system had insufficient resources to
complete the call.
ENOPROTOOPT The option is unknown.
ENOTSOCK The socket descriptor is invalid.
EFAULT The optname argument is invalid.
80 – shutdown()
Shuts down all or part of a bidirectional connection on a socket.
This function does not allow further receives or 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) ;
80.1 – 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 Do not allow further calls to recv() on the socket.
1 Do not allow further calls to send() on the socket.
2 Do not allow further calls to both send() and recv().
80.2 – Description
This function allows communications on a socket to be shut down
one direction at a time rather than all at once. You can use the
shutdown() function to shut down one direction in a full-duplex
(bidirectional) connection.
Related Functions
See also connect() and socket().
80.3 – Return Values
0 Successful completion.
-1 Error; errno is set to indicate the error.
80.4 – Errors
EBADF The socket descriptor is invalid.
EINVAL The how argument is invalid.
ENOBUFS The system has insufficient resources to
complete the call.
ENOTCONN The specified socket is not connected.
ENOTSOCK The socket descriptor is invalid.
81 – socket()
Creates an endpoint for communication by returning a special
kind of file descriptor called a socket descriptor, which is
associated with a TCP/IP Services socket device channel.
The $QIO equivalent is the IO$_SETMODE function.
Format
#include <types.h>
#include <socket.h>
int socket ( int af, int type, int protocol );
81.1 – Arguments
af
The address family used in later references to the socket.
Addresses specified in subsequent operations using the socket are
interpreted according to this family. Use one of the following:
o AF_INET for the IPv4 address family
o AF_INET6 for the IPv6 address family
o TCPIP$C_AUXS
For a network application server with the LISTEN flag enabled,
you specify the TCPIP$C_AUXS address family to obtain the
connected device socket created by the auxiliary server in
response to incoming network traffic.
type
The socket types are:
o SOCK_STREAM - Provides sequenced, reliable, two-way,
connection-based byte streams with an available out-of-band
data transmission mechanism.
o SOCK_DGRAM - Provides datagram transmissions. A datagram is a
connectionless, unreliable data transmission mechanism.
o SOCK_RAW - Provides access to internal network interfaces.
Available only to users with the 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, if many protocols exist, a particular
protocol must be specified with this argument. Use the protocol
number that is specific to the address family.
81.2 – Description
This function 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,
which are defined in the SOCKET.H header file and described in
the setsockopt() function section of this chapter.
Use the setsockopt() and getsockopt() functions to set and
get options. Options take an integer argument that should be
nonzero if the option is to be enabled or zero if it is to be
disabled. SO_LINGER uses a linger structure argument (see linger
Structure).
Related Functions
See also accept(), bind(), connect(), getsockname(),
getsockopt(), socketpair(), listen(), read(), recv(),
recvfrom(), recvmsg(), select(), send(), sendmsg(), sendto(),
shutdown(), and write().
81.3 – Return Values
x A file descriptor that refers to the socket
descriptor.
-1 Error; errno is set to indicate the error.
81.4 – Errors
EACCES The process does not have sufficient
privileges.
EAFNOSUPPORT The specified address family is not supported
in this version of the system.
EMFILE The per-process descriptor table is full.
ENETDOWN TCP/IP Services was not started.
ENFILE No more file descriptors are available for the
system.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory to increase the process descriptor
table.
EPERM The process is attempting to open a raw socket
and does not have SYSTEM privilege.
EPROTONOSUPPORT The socket in the specified address family is
not supported.
EPROTOTYPE The socket type is not supported by the
protocol.
ESOCKTNOSUPPORT The specified socket type is not supported in
this address family.
82 – socketpair()
Creates a pair of connected sockets.
Format
#include <sys/socket.h>
int socketpair (int domain, int type, int protocol, int
socket_vector[2]);
82.1 – Arguments
af
The address family in which the sockets are to be created. Use
one of the following:
o AF_INET for the IPv4 address family
o AF_INET6 for the IPv6 address family
o TCPIP$C_AUXS or a network application server with the LISTEN
flag enabled. Specify the TCPIP$C_AUXS address family to
obtain the connected device socket created by the auxiliary
server in response to incoming network traffic.
type
Specifies the type of sockets to be created. The socket types
are:
o SOCK_STREAM - Provides sequenced, reliable, two-way,
connection-based byte streams with an available out-of-band
data transmission mechanism.
o SOCK_DGRAM - Supports datagrams (connectionless, unreliable
data transmission mechanism).
o SOCK_SEQPACKET - Provides sequenced, reliable, bidirectional,
connection-mode transmission paths for records. A record can
be sent using one or more output operations and received using
one or more input operations, but a single operation never
transfers part of more than one record.
Use the MSG_EOR flag to determine the record boundaries.
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, if many protocols exist, a particular
protocol must be specified with this argument. Use the protocol
number that is specific to the address family.
If the protocol argument is 0, the function uses the default
protocol for the specified socket type.
If the protocol argument is non-zero, the function uses the
default protocol for the address family.
socket_vector
A 2-integer array to hold the file descriptors of the created
socket pair.
82.2 – Description
This function creates an unbound pair of connected sockets in a
specified address family, of a specified type, under the protocol
optionally specified by the protocol argument. The two sockets
will be identical. The file descriptors used in referencing the
created sockets are returned in socket_vector[0] and socket_
vector[1].
Appropriate privileges are required to use the socketpair()
function or to create some sockets.
Related Functions
See also socket().
82.3 – Return Values
0 Successful completion
-1 Error; errno is set to indicate the error.
82.4 – Errors
EACCES The process does not have sufficient
privileges.
EAFNOSUPPORT The specified address family is not supported
in this version of the system.
EMFILE The per-process descriptor table is full.
ENETDOWN TCP/IP Services was not started.
ENFILE No more file descriptors are available for the
system.
ENOBUFS The system has insufficient resources to
complete the call.
ENOMEM The system was unable to allocate kernel
memory to increase the process descriptor
table.
EPERM The process is attempting to open a raw socket
and does not have SYSTEM privilege.
EPROTONOSUPPORT The socket in the specified address family is
not supported.
EPROTOTYPE The socket type is not supported by the
protocol.
ESOCKTNOSUPPORT The specified socket type is not supported in
this address family.
83 – write()
Writes bytes from a buffer to a file or socket.
The $QIO equivalent is the IO$_WRITEVBLK function.
Format
#include <unixio.h>
int write ( int d, void *buffer, int nbytes );
83.1 – Arguments
d
A descriptor that refers to a socket or file.
buffer
The address of a buffer from which the output data is to be
taken.
nbytes
The maximum number of bytes involved in the write operation.
83.2 – Description
This function attempts to write a buffer of data to a socket or
file.
Related Functions
See also socket().
83.3 – Return Values
x The number of bytes written to the socket or
file.
-1 Error; errno is set to indicate the error.
83.4 – Errors
EPIPE The socket is shut down for writing or is
connection oriented, and the peer is closed or
shut down for reading. In the latter case, if
the socket is of type SOCK_STREAM, the SIGPIPE
signal is generated to the calling process.
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 a negative value.
EAGAIN The O_NONBLOCK flag is set on this file, and
the process is delayed in the write operation.
EBADF The d argument does not specify a valid file
descriptor that is open for writing.
EINTR A write() function on a pipe is interrupted by
a signal, and no bytes have been transferred
through the pipe.
EINVAL On of the following errors occurred:
o The STREAM or multiplexer referenced
by d is linked (directly or indirectly)
downstream from a multiplexer.
o The file position pointer associated with
the d argument was a negative value.
EPERM An attempt was made to write to a socket of
type SOCK_STREAM that is not connected to a
peer socket.
EPIPE An attempt was made to write to a pipe that
has only one end open.
An attempt was made to write to a pipe or FIFO
that is not opened for reading by any process.
A SIGPIPE signal is sent to the process.
ERANGE An attempt was made to write to a STREAM
socket where the value of nbytes is outside
the specified minimum and maximum range, and
the minimum value is nonzero.