HPUX ipcrecv[2]
ipcrecv(2) ipcrecv(2)
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:
o Establish a virtual circuit connection that was initiated with
ipcconnect() (see ipcconnect(2)),
o Receive data on a previously established virtual circuit
connection.
After a program calls ipcconnect(), it must call ipcrecv() to complete
the connection. When ipcrecv() is called to finish establishing a
connection, no data is returned in the data parameter and the dlen
parameter is ignored. An exception ipcselect() (see 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:
o Normal reading: Data is moved from the connection queue into
the user's buffer.
o 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.
o 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.
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
ipcrecv(2) ipcrecv(2)
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() (see 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(). 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:
o Is the endpoint of a virtual circuit
connection that has not yet been
established, or
o Is the endpoint of an established virtual
circuit on which data will be received.
data (output parameter) A pointer to a data buffer for
holding 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
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
ipcrecv(2) ipcrecv(2)
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 ERRORS 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.
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
ipcrecv(2) ipcrecv(2)
RETURN VALUE
None. Errors are returned in the result parameter.
ERRORS
[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:
o Before the connection completed
(first call to ipcrecv() and the
socket is in synchronous mode),
o Before any data arrived
(connection established, socket
in synchronous mode,
NSF_DATA_WAIT flag not set), or
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
ipcrecv(2) ipcrecv(2)
o 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.
SEE ALSO
ipcconnect(2), ipccontrol(2), ipccreate(2), ipcdest(2),
ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnamerase(2),
ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2),
ipcshutdown(2), addopt(3N), initopt(3N), ipcerrmsg(3N),
optoverhead(3N), readopt(3N).
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992