ChannelDestroy(), ChannelDestroy_r()

Updated: April 19, 2023

Destroy a communications channel

Synopsis:

#include <sys/neutrino.h>

int ChannelDestroy( int chid );

int ChannelDestroy_r( int chid );

Arguments:

chid
The channel ID, returned by ChannelCreate(), of the channel that you want to destroy.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

These kernel calls remove a channel specified by the channel ID chid argument. Once destroyed, any attempt to receive messages or pulses on the channel will fail. Any threads that are blocked on the channel by calling MsgReceivev() or MsgSendv() will be unblocked and return with an error.

The ChannelDestroy() and ChannelDestroy_r() functions are identical except in the way they indicate errors. See the Returns section for details.

When the channel is destroyed, all server connection IDs (scoids) become invalid. The client connection IDs (coids) are also marked invalid but remain in existence until the client removes them by calling ConnectDetach(). An attempt by the client to use one of these invalid connections using MsgSend*(), MsgSendv*(), or MsgSendPulse() will return with an error.

A server typically destroys its channels prior to its termination. If it fails to do so, the kernel destroys them automatically when the process dies.

Blocking states

These calls don't block.

Returns:

The only difference between these functions is the way they indicate errors:

ChannelDestroy()
If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
ChannelDestroy_r()
EOK is returned on success. This function does NOT set errno. If an error occurs, the function may return any value in the Errors section.

Errors:

EINVAL
The channel specified by chid doesn't exist.

Classification:

QNX Neutrino

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes