hp.com home products and services support and drivers solutions how to buy
cd-rom home
End of Jump to page title
HP OpenVMS systems
documentation

Jump to content


HP TCP/IP Services for OpenVMS

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


Previous Contents Index

4.2 Socket API Functions

This section describes functions that comprise the Sockets API and that are supported by TCP/IP Services.


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)


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. See Section 3.2.12 for a description of the sockaddr structure.

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() .


Return Values

x A positive integer that is a descriptor for the accepted socket.
-1 Error; errno is set to indicate the error.

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.

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)


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. See Section 3.2.12 for a description of the sockaddr structure.

namelen

The size, in bytes, of the structure pointed to by name.

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() .


Return Values

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

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.

close()

Closes a connection and deletes a socket descriptor.

The $QIO equivalent is the $DASSGN system service.


Format

#include <unixio.h>

int close ( s );


Argument

s

A socket descriptor.

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() .


Return Values

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

Errors

EBADF The socket descriptor is invalid.
EINTR The close() function was interrupted by a signal that was caught.

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)


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.

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() .


Return Values

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

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.

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 );


Argument

s

A socket descriptor.

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.

Return Values

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

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);


Argument

channel

A valid SDC.

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.

Return Values

x The socket descriptor.
- 1 Indicates an error; the socket descriptor cannot be allocated.

endhostent()

Closes hosts database file.

Format

#include <netdb.h>

void endhostent (void);


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() .


endnetent()

Closes the networks database file.

Format

#include <netdb.h>

void endnetent (void);


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() .


endprotoent()

Resets the index for the protocols table.

Format

#include <netdb.h>

void endprotoent (void);


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() .


endservent()

Closes the services database file.

Format

#include <netdb.h>

void endservent (void);


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() .


freeaddrinfo()

Frees system resources used by an address information structure.

Format

#include <netdb.h>

void freeaddrinfo ( struct addrinfo *ai );


Arguments

ai

Points to an addrinfo structure to be freed. The NETDB.H header file defines the addrinfo structure.

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.


Previous Next Contents Index