ipcconnect(2)

NAME

ipcconnect − initiate a connection to another process

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcconnect(

ns_int_t calldesc,
ns_int_t destdesc,
ns_int_t *flags,
short opt[],
ns_int_t *vcdesc,
ns_int_t *result);

DESCRIPTION

ipcconnect() is used to initiate a virtual circuit on which data can be sent and received. When ipcconnect() returns, a connection is not yet established; a successful return only indicates that a connection request was sent without error. Actively establishing a virtual circuit with Net IPC calls is a two-step process:

• ipcconnect() is called to request a connection, then

• ipcrecv(3N) is called to find out if a connection initiated with ipcconnect() was successfully established.

The opt parameter can be used to specify the number of bytes you expect to send and receive on the connection. The default for both sending and receiving is 100 bytes. This information is passed to the underlying protocol. When TCP is the underlying protocol, it limits the number of bytes that can be queued on a socket to the specified value.

PARAMETERS

calldesc (input parameter)
NS_NULL_DESC should be specified. A valid call socket descriptor can be specified to ensure backward compatibility.

destdesc (input parameter)
A destination descriptor obtained by calling ipclookup() or ipcdest() (see ipclookup(3N) and ipcdest(3N)).

flags (input parameter)
Either 0 or a pointer to 0. All other values are reserved for future use.

opt (input parameter)
Options for this call. If no options are used, this parameter can be null. Otherwise, see below.

vcdesc (output parameter)
A pointer to a virtual circuit number that can be used in subsequent Net IPC calls to reference the connection.

result (output parameter)
See ERRORS below.

OPTION PARAMETER

NSO_MAX_SEND_SIZE (optioncode = 3) (datalength = 2) A two-byte integer specifying the maximum number of bytes that can be sent with a single ipcsend () call on this connection (see ipcsend(3N)). Range: 1 to 32000 bytes. Default: 100 bytes.

NSO_MAX_RECV_SIZE (optioncode = 4) (datalength = 2) A two-byte integer specifying the maximum number of bytes that can be received with a single ipcrecv() call on this connection (see ipcrecv(3N)). Range: 1 to 32,000 bytes. Default: 100 bytes.

RETURN VALUE

None. Errors are returned in the result parameter.

ERRORS

[NSR_ADDR_NOT_AVAIL] The protocol address specified by the destination descriptor is 0, which is illegal for connection establishment, OR there is no available interface to the destination network.

[NSR_BOUNDS_VIO] A length or offset value in the option parameter is illegal or one of the pointer arguments is invalid.

[NSR_DESC] The calldesc argument is not NSR_NULL_DESC or a valid socket descriptor, or the destdesc argument is not a valid destination descriptor.

[NSR_DEST_UNREACHABLE] The network or host specified by the destination descriptor is unreachable from this host at this time.

[NSR_DUP_OPTION] A particular option is defined more than once in the opt parameter.

[NSR_FLAGS] An unsupported flag is set in the flags parameter.

[NSR_KIND_AND_PROTOCOL] The requested protocol is not supported in the default domain.

[NSR_MSGSIZE] The value specified in NSO_MAX_SEND_SIZE or NSO_MAX_RECV_SIZE is invalid.

[NSR_NO_DESC_AVAILABLE] The process exceeded the system-defined number of file and socket descriptors that can be open at a time (see getrlimit(2)).

[NSR_NO_ERROR] The call was successful.

[NSR_NO_FILE_AVAILABLE] The system cannot allocate a file structure at this time.

[NSR_NO_MEMORY] Sufficient system memory is not available to execute this call at this time.

[NSR_NOT_ALLOWED] An unsupported flag is set in the flags parameter.

[NSR_NOT_CALL_SOCKET] The calldesc argument is not an NS_CALL socket.

[NSR_OPT_OPTION] An option in the opt parameter is unknown or unsupported.

[NSR_OPT_SYNTAX] A length or offset value in the opt parameter is invalid.

[NSR_PROTOCOL] The requested protocol is not supported.

[NSR_SIGNAL_INDICATION] The call aborted due to a signal.

AUTHOR

ipcconnect() was developed by HP.

Museum

Related Articles