Series 300 and 800 Only

NAME

ipccontrol() − performs special operations on NetIPC sockets

SYNOPSIS

#include <sys/ns_ipc.h>

void ipccontrol (descriptor,request,wrtdata,wlen,readdata,rlen,flags,result);
ns_int_t descriptor,request,wlen,*rlen,*flags,*result;
char *readdata, *wrtdata;

DESCRIPTION

The ipccontrol call is used to manipulate sockets in special ways.  The type of request is specified by placing a certain request code in the request parameter.  Although all of the request types require the descriptor, request and result parameters, some of the parameters are ignored for certain requests.  If NSC_SEND_THRESH_RESET, NSC_TIMEOUT_RESET, or NSC_RECV_THRESH_RESET is specified, the wrtdata and wlen parameters are used.  If NSC_TIMEOUT_GET, NSC_RECV_THRESH_GET, NSC_SEND_THRESH_GET or NSC_GET_NODE_NAME is specified, the readdata and rlen parameters are used. 
 
Because ipccontrol requests operate on sockets, all processes that own descriptors to a particular socket will be affected by ipccontrol operations performed on that socket. 
 
For example, one process can change a socket’s read or write threshold, synchronous time-out interval or synchronous/asynchronous mode while another process is reading, writing or selecting on that socket.  Exactly when the process that is sharing the socket will be affected by these operations cannot be reliably predicted. Reads, writes and selects in progress may complete after using either the previous, new, or a combination of the previous and old values. Refer to the NetIPC programmer’s manual for your system for more information about synchronous and asynchronous mode and read and write thresholds.
 
This routine can be linked into a program by giving the -lnsipc option to cc(1) or ld(1). 

PARAMETERS

descriptor (input parameter) The descriptor that refers to the socket to be manipulated.  May be a call socket descriptor or VC socket descriptor depending on the request code specified in the request parameter.  If the request parameter is set to NSC_GET_NODE_NAME, you can specify NS_NULL_DESC or -1 in this parameter. 

request (input parameter) Request code.  Defines which operation is to be performed.  See below. 

wrtdata (input parameter) A data buffer or data vector used to pass time-out and threshold information. 

wlen (input parameter) Length in bytes of the wrtdata data buffer. 

readdata (output parameter) A data buffer or data vector used to contain any data returned by the call. 

rlen (input/output parameter) The length in bytes of the readdata data buffer.  On output, this parameter will contain the total number of bytes returned to the process. 

flags (input parameter) 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.  See "Diagnostics" below for more information. 

REQUEST PARAMETER

NSC_NBIO_ENABLE
(request code 1) Place the socket referenced in the descriptor parameter in asynchronous mode.  For ipcsend and ipcrecv calls, this is the VC socket described by the VC socket descriptor in the vcdesc parameter.  For ipcrecvcn it is the call socket described by the call socket descriptor in the calldesc parameter. 

NSC_NBIO_DISABLE
(request code 2) Place the socket referenced in the descriptor parameter in synchronous mode.  For ipcsend and ipcrecv calls this is the VC socket described by the VC socket descriptor in the vcdesc parameter.  For ipcrecvcn, it is the call socket described by the call socket descriptor in the calldesc parameter. 

NSC_TIMEOUT_RESET
(request code 3) Change the referenced socket’s synchronous time-out. The default time-out value is 60 seconds. For ipcsend and ipcrecv calls, this is the VC socket described by the VC socket descriptor in the vcdesc parameter.  For ipcrecvcn, it is the call socket described by the call socket descriptor in the calldesc parameter.  The time-out value is given in tenths of seconds.  (For example, a value of 1200 would indicate 120 seconds.)  The new time-out value is treated as a 16-bit signed integer and must be placed in the first two bytes of the wrtdata parameter.  The time-out value must be in the range of zero to 32767.  Negative values have no meaning and will result in error.  A value of zero sets the time-out to infinity.  The time-out will not be reset if the referenced socket is switched to asynchronous mode and then back to synchronous mode. 

NSC_TIMEOUT_GET
(request code 4) Return the synchronous time-out value for the socket referenced in the descriptor parameter.  For ipcsend and ipcrecv calls, this is the VC socket described by the VC socket descriptor in the vcdesc parameter.  The time-out value is treated as a 16-bit signed integer and is returned in the readdata parameter. 

NSC_RECV_THRESH_RESET
(request code 1000) Change the read threshold of the VC socket referenced in descriptor parameter.  (Read thresholds are one byte by default.) The descriptor parameter must reference a VC socket descriptor.  The new read threshold value must be placed in the first two bytes of the wrtdata parameter. 

NSC_SEND_THRESH_RESET
(request code 1001) Change the write threshold of the VC socket referenced in the descriptor parameter.  (Write thresholds are one byte by default.)  The descriptor parameter must reference a VC socket descriptor.  The new write threshold value must be placed in the first two bytes of the wrtdata parameter. 

NSC_RECV_THRESH_GET
(request code 1002) Return the current write threshold for the VC socket referenced in the descriptor parameter.  The descriptor parameter must reference a VC socket descriptor.  The write threshold is treated as a 16-bit signed integer and is returned in the readdata parameter. 

NSC_SEND_THRESH_GET
(request code 1003) Return the current read threshold for the VC socket referenced in the descriptor parameter.  The descriptor parameter must reference a VC socket descriptor.  The read threshold is treated as a 16-bit signed integer and is returned in the readdata parameter. 

NSC_GET_NODE_NAME
(request code 9008) Return the fully-qualified local node name.  The node name is returned in the readdata parameter. 

FLAGS PARAMETER

NSF_VECTORED (bit 31)
(input parameter)  When set, this bit indicates that the wrtdata and readdata parmeters are data vectors and not data buffers. 

RETURNS

None.  Errors are returned in the result parameter. 

AUTHOR

HP

SEE ALSO

ipcsend(2), ipcrecv(2), ipcrecvcn(2). 

DIAGNOSTICS

[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