ipcrecv(2)

Requires Optional LAN/X.25 Software

NAME

ipcrecv − establish an NetIPC virtual circuit connection OR receive data on an established connection

SYNOPSIS

#include <sys/ns_ipc.h>

void ipcrecv(

ns_int_t vcdesc,
void ∗data,
ns_int_t ∗dlen,
ns_int_t ∗flags,
short opt[],
ns_int_t ∗result);

DESCRIPTION

ipcrecv serves two purposes:

• Establish a virtual circuit connection that was initiated with ipcconnect(2),

• Receive data on a previously established virtual circuit connection.

After a program calls ipcconnect(2), it must call ipcrecv to complete the connection. When ipcrecv is called to complete connection establishment, no data is returned in the data parameter and the dlen parameter is ignored. An exception ipcselect(2) can be performed to determine whether connections are pending on a call socket.

When ipcrecv is called to receive data queued on a established connection, several different alternatives are available:

• Normal reading: Data is moved from the connection queue into the user’s buffer.

• Preview reading: This alternative is specified by setting the NSF_PREVIEW bit (bit 30) of the flags parameter. When this bit is set, data is copied into the process’s buffer, but still remains in the connection queue. Consequently, the next ipcrecv call reads the same data.

• Vectored or "scattered" reading: The calling process can pass a data vector argument that describes one or more locations. Received data is then placed into these locations. This alternative can be used with both the normal and the preview read described above, and is specified by setting the NSF_VECTORED bit (bit 31) of the flags parameter.

For vectored reads an iovec structure contains the data vector. An iovec structure can be defined as:

struct iovec {
char *iov_base;
unsigned iov_len;
};

and the normal type for the data argument can be replaced by:

struct iovec *data;

Each iovec entry specifies the base address and length of an area in memory where data should be placed. ipcrecv always fills one area completely before proceeding to the next area.

ipcrecv behavior varies, depending on whether the socket referenced is in synchronous or asynchronous mode. A socket is in synchronous mode by default. It can be placed in asynchronous mode by calling ipccontrol(2). By default, calls that block reach their timeout limit in 60 seconds. The length of the timeout period can be changed by calling ipccontrol(2). Refer to ipccontrol(2) for more information.

If the socket referenced by ipcrecv is in synchronous mode and no data is queued on the connection, the call blocks until data arrives or the socket timer expires.

If the socket referenced by ipcrecv is in asynchronous mode and no data is queued on the connection, NSR_WOULD_BLOCK is returned in the result parameter.

Parameters

vcdesc (input parameter) "virtual circuit" socket descriptor. Refers to a socket that:

• Is the endpoint of a virtual circuit connection that has not yet been established, or

• Is the endpoint of an established virtual circuit on which data will be received.

data (output parameter) A pointer to a data buffer that will hold the received data, or a pointer to an array of data vectors describing the locations where the data is to be placed.

dlen (input/output parameter) If data is a data buffer, dlen is the maximum number of bytes that can be received. If data is a data vector, dlen refers to the length of the data vector in bytes. As a return parameter, dlen indicates how many bytes were actually received. If ipcrecv is used to establish a connection (not to receive data), dlen is meaningless on input and a value of zero (0) is returned on output.

flags (input/output parameter) See below.

opt (input parameter) A pointer to a NetIPC options buffer. See below.

result (output parameter) The error code returned. Refer to DIAGNOSTICS below for more information.

Flags Parameter

Flags are only valid on an established connection.

NSF_DATA_WAIT (bit 20) (input parameter) This flag exists for backward compatibility. Existing programs that use this flag may suffer performance degradation due to network congestion avoidance algorithms in the networking protocol code. This flag should be removed from those programs

NSF_MORE_DATA (bit 26) (output parameter) This bit is always set for backwards compatibility.

NSF_PREVIEW (bit 30) (input parameter) When this bit is set, data queued on the connection may be previewed. Data is placed in the data parameter but not removed from the connection queue. Since the data remains in the queue, the next ipcrecv call reads the same data.

NSF_VECTORED (bit 31) (input parameter) When set, this bit indicates that data is a data vector and not a data buffer.

Opt Parameter

Options are only valid when ipcrecv is issued against an established connection.

NSO_DATA_OFFSET (optioncode = 8) (datalength = 2) A two-byte integer that defines a byte offset from the beginning of a data buffer where NetIPC is to begin placing data. This option is valid only if data is a data buffer and not a data vector.

RETURN VALUE

None. Errors are returned in the result parameter.

DIAGNOSTICS

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

[NSR_DESC] The vcdesc argument is not a valid socket descriptor

[NSR_DLEN] The specified dlen parameter is invalid.

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

[NSR_MESSAGE_SIZE] The value in the dlen exceeds the maximum limit for this socket. The default maximum is 100 bytes. You can use ipccontrol to alter this value.

[NSR_NO_ERROR] The call was successful.

[NSR_NOT_CONNECTION] The vcdesc parameter did not reference a VC socket.

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

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

[NSR_REMOTE_ABORT] The connection was aborted due to an action by the peer.

[NSR_REMOTE_RELEASED] The connection was released due to action by the peer.

[NSR_SIGNAL_INDICATION] The call aborted due to a signal received.

[NSR_SOCKET_TIMEOUT] The socket timer expired:

• Before the connection completed (first call to ipcrecv and the socket is in synchronous mode),

• Before any data arrived (connection established, socket in synchronous mode, NSF_DATA_WAIT flag not set), or

• Before the requested amount of data arrived (connection established, socket in synchronous mode, NSR_DATA_WAIT flag set).

[NSR_TOO_MANY_VECTS] The number of data vectors exceeds the maximum limit of 16.

[NSR_VECT_COUNT] A negative data length was specified in the iovec.

[NSR_WOULD_BLOCK] The connection is still pending; the data present is less than requested, the socket in asynchronous mode, and the NSF_DATA_WAIT flag is set; or no data is present, and the socket is in asynchronous mode with the NSF_DATA_WAIT flag not set.

AUTHOR

ipcrecv was developed by HP.

Museum

Related Articles