NAME

ipccontrol − perform special operations on a NetIPC socket

SYNOPSIS

#include <sys/ns_ipc.h>

void ipccontrol(

ns_int_t descriptor,
ns_int_t request,
const void *wrtdata,
ns_int_t wlen,
void *readdata,
ns_int_t *rlen,
ns_int_t *flags,
ns_int_t *result);

DESCRIPTION

ipccontrol() is used to manipulate Net IPC sockets.  The type of request is specified in the request parameter.  Some parameters are optional and not used in all requests.  If wrtdata is not used, wlen must be zero.  If readdata is unused, rlen must be zero. 

All processes that own descriptors for a particular socket are affected by ipccontrol() operations performed on that socket.  For example, one process can change a socket’s read or write threshold, synchronous timeout 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 new values. 

Parameters

descriptor (input parameter)
The descriptor that refers to the socket to be manipulated.

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

wrtdata (input parameter)
A data buffer used to pass timeout and threshold information.

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

readdata (output parameter)
A data buffer 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 contains the total number of bytes returned to the process. 

flags (input parameter)
Reserved for future use. This parameter should be 0 or a pointer to 0.

result (output parameter)
The error code returned. See ERRORS below for more information. 

Request Parameter

NSC_NBIO_ENABLE (request code 1)
Place socket referenced by descriptor in asynchronous mode. 

NSC_NBIO_DISABLE (request code 2)
Place socket referenced by descriptor in synchronous mode. 

NSC_TIMEOUT_RESET (request code 3)
Change the referenced socket’s synchronous timeout. The default timeout value is 60 seconds. The timeout value is specified in tenths of seconds (for example, a value of 1200 indicates 120 seconds). The new timeout value is treated as a 16-bit signed integer, and must be placed in the first two bytes of the wrtdata parameter.  The timeout value must be in the range of zero to 32767. Negative values have no meaning and will result in an error. A value of zero sets the timeout to infinity. The timeout is not reset if the referenced socket is switched to asynchronous mode then back to synchronous mode.

NSC_TIMEOUT_GET (request code 4)
Return the synchronous timeout value for the socket referenced in the descriptor parameter.  The timeout 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)
Obsolescent. Use getnodename(2) instead.

RETURN VALUE

None.  Errors are returned in the result parameter. 

ERRORS

[NSR_BOUNDS_VIO] One of the pointer arguments is invalid. 

[NSR_DESC] The argument descriptor is not a valid Net IPC socket descriptor. 

[NSR_DLEN] The specified wlen or rlen parameter is invalid. 

[NSR_NO_ERROR] The call was successful. 

[NSR_REQUEST] The request was unknown. 

[NSR_TIMEOUT_VALUE] An illegal timeout value was specified. 

[NSR_THRESH_VALUE] An illegal threshold value was specified. 

AUTHOR

ipccontrol() was developed by HP. 

SEE ALSO

ipcconnect(2), ipccreate(2), ipcdest(2), ipcgetnodename(2), ipclookup(2), ipcname(2), ipcnamerase(2), ipcrecv(2), ipcrecvcn(2), ipcselect(2), ipcsend(2), ipcsetnodename(2), ipcshutdown(2), addopt(3N), initopt(3N), ipcerrmsg(3N), optoverhead(3N), readopt(3N). 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992