IPCSHUTDOWN(2)
Series 300 and 800 Only
NAME
ipcshutdown() − releases a descriptor
SYNOPSIS
#include <sys/ns_ipc.h>
void ipcshutdown (descriptor,flags,opt,result);
ns_int_t descriptor,*flags,*result;
short int opt[];
DISCUSSION
The ipcshutdown call is used to release a descriptor. The descriptor referenced may be a call socket descriptor, VC socket descriptor, or destination descriptor. How ipcshutdown functions depends on which type of descriptor is being used.
(1) Call Socket Descriptor. The descriptor is released along with any names associated with it. The process that released the call socket descriptor may no longer use it, and all connection requests queued to that descriptor are aborted. The call socket referenced by the descriptor is destroyed along with the descriptor only if the descriptor being released is the last descriptor for that socket. If another process, or processes, have a descriptor for the same socket, these duplicate descriptors are not affected. Since system resources are used when a call socket is created, you may want to release your call socket descriptors when they are no longer needed. A call socket descriptor is needed as long as a process is expecting to receive a connection request on that socket. After the connection request is received via ipcrecvcn, and as long as no other connection requests are expected for that call socket descriptor, the descriptor can be released. Similarly, a process that requests a connection can release its call socket descriptors any time after its call to ipcconnect, as long as it is not expecting to receive a connection request on that descriptor. Using ipcshutdown to release a call socket descriptor does not affect any VC sockets.
(2) Destination Descriptor. The descriptor is released along with any names associated with it in the local socket registry. The process that released the destination descriptor may no longer use it. The addressing information stored in conjunction with the descriptor is destroyed along with the descriptor only if the descriptor being released is the sole descriptor for that information. If another process, or processes, have a descriptor for the same information, these duplicate descriptors, and any names associated with the descriptors, are not affected. Because destination descriptors also require system resources, you may want to release them when they are no longer needed.
(3) VC Socket Descriptor. The VC socket descriptor is released and the referenced connection is aborted and is no longer available for sending or receiving data. The VC socket descriptor is released along with the descriptor only if the descriptor being released is the last descriptor for that socket. If another process, or processes, have a descriptor for the same VC socket, these duplicate descriptors are not affected. Because ipcshutdown takes effect very quickly, all of the data that is in transit on the connection, including any data that has already been queued on the destination VC socket, may be destroyed when the connection is shut down. Obtaining confirmation from the receiver is the only way a sender will know that data sent was actually received. Shutting down a VC socket does not affect any call sockets.
Although NetIPC guarantees that data will be delivered reliably, this guarantee is contingent upon a functioning network; data may not be received if nodes crash, network links fail, or peer processes abort. If the process calling ipcshutdown sends important data to its peer process just prior to shutting that process down, it is recommended that the calling process receive a confirmation from the peer process before calling ipcshutdown to ensure that the data was received.
Refer to the "Shutting Down a Connection" in the NetIPC programmer’s manual for your system for information about using ipcshutdown to gracefully release a connection.
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 to be released. May be a call socket descriptor, VC socket descriptor, or destination descriptor.
flags (input parameter) This parameter is reserved for future use. All bits must be clear (not set). Refer to the NetIPC programmer’s manual for your system for a complete description of this parameter.
opt (input parameter) No options are defined for this call. This parameter must be set to zero (0) or you may pass the constant (C programs only) NSO_NULL in its place.
result (output parameter) The error code returned; zero or NSR_NO_ERROR if no error. Refer to "Diagnostics" below for more information.
RETURNS
None. Errors are returned to the result parameter.
AUTHOR
HP.
SEE ALSO
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