IPCRECV(2)
Series 300 and 800 Only
NAME
ipcrecv() − establishes an NetIPC virtual circuit connection or receives data on a previously established connection
SYNOPSIS
#include <sys/ns_ipc.h>
void ipcrecv (vcdesc,data,dlen,flags,opt,result);
ns_int_t vcdesc,*dlen,*flags,*result;
short int opt[];
char *data;
DESCRIPTION
ipcrecv has two functions: (1) establish a virtual circuit connection that was initiated with ipcconnect; (2) receive data on a previously established virtual circuit connection
When ipcrecv is successfully called to establish a connection, no data is returned in the data parameter and zero is returned in the result parameter. If the call is unsuccessful, a non-zero value is returned in the result parameter. The call could be unsuccessful for the following reasons:
(1) NSR_SOCKET_TIMEOUT Error Received. The synchronous timer expired before the connection could be established. The connection is still pending and ipcrecv should be called again to establish the connection.
(2) NSR_WOULD_BLOCK Error Received. The VC socket referenced by ipcrecv is in asynchronous mode and the call could not be satisfied. The connection is still pending and ipcrecv should be called again to establish the connection. You can perform an exception select on the referenced socket to determine if a connection is up prior to calling ipcrecv to establish the connection.
(3) NSR_SIGNAL_INDICATION Error Received. A signal indication was received. For more information on signals, refer to the HP-UX Reference Manual.
(4) Other Errors Received. If the connection could not be established for a reason other than those listed above, the referenced VC socket should be shut down by calling ipcshutdown.
When ipcrecv is called to receive data queued on a previously established connection, several different alternatives are available:
(1) Normal reading. Data is dequeued from the connection and placed into the user’s buffer.
(2) 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 placed in the process’s buffer, but not dequeued from the connection. Consequently, the next ipcrecv call will read the same data. Because NSF_PREVIEW enables a process to determine what a data buffer contains before actually reading it, it is especially useful to set this bit when the receiving process must assemble messages from the byte streams that it receives. For example, if the sending process places the length of its "message" in the first two bytes of its send buffer, the receiving process can use NSF_PREVIEW to extract the length information from the data received. When the buffer is received again with a subsequent ipcrecv call, the receiving process can specify this length information in the dlen parameter and thus reassamble the "message."
(3) Vectored or "scattered" reading. The calling process may pass a data vector argument that describes one or more locations. Received data will be placed into these locations. This alternative can be used with both the normal and preview reads 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-in one area completely before proceeding to the next area.
The ipcrecv call functions differently depending on whether the socket referenced is in synchronous or asynchronous mode, and whether or not the NSF_DATA_WAIT bit (bit 20) is set in the flags parameter.
The following paragraphs describe how the ipcrecv call functions depending on whether or not the socket referenced is in synchronous or asynchronous mode, and whether or not the NSF_DATA_WAIT flag is set. (When a socket is created, it is placed in synchronous mode by default. You can place a socket in asynchronous mode by calling ipccontrol. Refer to ipccontrol for more information.
The "amount requested" by an ipcrecv call refers to the number of bytes specified by the dlen parameter or the amount specified in the data vector if the NSF_VECTORED flag is set.
Synchronous I/O, NSF_DATA_WAIT set. If the socket referenced by ipcrecv is in synchronous mode and the NSF_DATA_WAIT bit (bit 20) is set, the calling process will block until (1) the amount of data queued on the connection is greater than or equal to the amount requested in the dlen parameter, (2) the call times out, or (3) a signal is received. If the data queued on the connection is less than dlen bytes, ipcrecv will suspend the calling process and the synchronous timer will be set. If the timer expires before enough data arrives to satisfy the request, the calling process will resume and an NSR_SOCKET_TIMEOUT error (code 59) will be returned indicating that a time-out occurred. (The synchronous time-out can be adjusted by calling ipccontrol.)
Synchronous I/O, NSF_DATA_WAIT not set. If the socket referenced by ipcrecv is in synchronous mode and the NSF_DATA_WAIT bit (bit 20) is not set, the the calling process will block until (1) some amount of data is queued on the connection (the amount of data queued may or may not be the amount requested, and may be as little as one byte), (2) the call times out, (3) a signal is received, or (4) the connection goes down. If no data is queued on the connection within the synchronous time-out period, the calling process will resume and an NSR_SOCKET_TIMEOUT error (code 59) will be returned indicating that a time-out occurred.
Asynchronous I/O, NSF_DATA_WAIT set. If the socket referenced by ipcrecv is in asynchronous mode and the NSF_DATA_WAIT bit is set, an NSR_WOULD_BLOCK (code 56) error is returned to the calling process if the amount of data queued on the connection is less than the amount requested. The calling process is not suspended awaiting the arrival of data. You can perform a read select on the referenced socket by invoking ipcselect. ipcselect determines whether or not a socket is readable prior to calling ipcrecv to receive data. (Refer to ipcselect for more information.)
Asynchronous I/O, NSF_DATA_WAIT not set. If the socket referenced by ipcrecv is in asynchronous mode and the NSF_DATA_WAIT bit is not set, as little as one byte of data will satisfy the ipcrecv request. However, if no data is queued to the connection, an NSR_WOULD_BLOCK error is returned.
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1)1
PARAMETERS
vcdesc (input parameter) VC socket descriptor. Refers to a VC socket that: (1) is the endpoint of a virtual circuit connection that has not yet been established, or (2) is the endpoint of a previously established virtual circuit on which data will be received.
data (output parameter) A data buffer that will hold the received data, or a data vector describing the location where the data is to be placed.
dlen (input/output parameter) If the data parameter is a data buffer, the dlen parameter is the maximum number of bytes you are willing to receive. If the data parameter is a data vector, the dlen parameter refers to the length of the data vector in bytes. As a return parameter, the dlen parameter indicates how many bytes were actually received. If ipcrecv is used to establish a connection (not to receive data), the dlen parameter is meaningless on input and a value of zero (0) is returned on output.
flags (input/output parameter) See below. Refer to the NetIPC programmer’s manual for your system for a complete descripton of this parameter.
opt (input parameter) An array of options and associated information. See below. Refer to the NetIPC programmer’s manual for your system for a complete description of this parameter.
result (output parameter) The error code returned; zero or NSR_NO_ERROR if no error. Refer to "Diagnostics" below for more information.
FLAGS PARAMETER
NSF_DATA_WAIT (bit 20)
(input parameter) When this bit is set, ipcrecv will never successfully complete receiving less data than it requested in the dlen parameter. If this bit is not set, ipcrecv may complete receiving less data than it requested in dlen. This bit is only valid when ipcrecv is issued against an established connection.
NSF_MORE_DATA (bit 26)
(output parameter) When set, this bit indicates that the data received was not delimited by and end-of-message marker. Since user processes always employ stream mode, this bit will always be set. (The Transmission Control Protocol decides how much data to transmit, but it does not delimit the data transmitted in the form of an individual message.) This bit is only set when ipcrecv is issued against an established connection.
NSF_PREVIEW (bit 30)
(input parameter) When set, this bit allows you to preview the data queued on the connection. Data is placed in the data parameter but not dequeued from the connection. Because the data is not dequeued, the next ipcrecv call will read the same data. This bit is only valid when ipcrecv is issued against an established connection.
NSF_VECTORED (bit 31)
(input parameter) When set, this bit indicates that the data parameter is a data vector and not a data buffer. This bit is only valid when ipcrecv is issued against an established connection.
OPT PARAMETER
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 the data. This option is valid only if the data parameter is a data buffer and not a data vector.
RETURNS
None. Errors are returned in the result parameter.
AUTHOR
HP.
SEE ALSO
ipcshutdown(2), ipccontrol(2), ipcselect(2).
DIAGNOSITCS
[NSR_NO_ERROR] The call was successful.
[NSR_xxxx] Refer to the errors listed in the NetIPC programmer’s manual for your system.
Hewlett-Packard Company — May 11, 2021