MsgError(), MsgError

Unblock a client and set its error code

Synopsis:

#include <sys/neutrino.h>

int MsgError( int rcvid,
              int error );

int MsgError_r( int rcvid,
                int error );

Arguments:

rcvid: The receive ID that MsgReceive*() returned.
error: The error code that you want to set for the client.

Library:

libc

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

Description:

The MsgError() and MsgError_r() kernel calls unblock the client's MsgSend*() call and set the client's error code to error. No data is transferred.

These functions are identical except in the way they indicate errors. See the Returns section for details.

When a server receives an unblock pulse, it typically can't determine why. In QNX Neutrino 7.0.1 or later, the server can call MsgError() with an error of -1; in this case, MsgError() sets the client's error code to whatever error the kernel stored when the unblock pulse was sent. Calling MsgError(rcvid, -1) under any other circumstances yields undefined results; the client will receive some garbage error value.

If error is EOK, the MsgSend*() call indicates success. If the error is any other value, the MsgSend*() call returns one of the following values:

For MsgSend*_r() calls, the negative of the error value that is passed.
For all other MsgSend*() calls, -1 with errno set to the specified value.

Note: An error number of ERESTART causes the sender to immediately call MsgSend*() again. Since send and reply buffers passed to MsgSend() may overlap, you shouldn't use ERESTART after a call to MsgWrite().

Blocking states

None for the local case. In the network case:

STATE_REPLY: The calling thread is waiting for a network operation to complete. The calling thread is marked as REPLY-blocked on itself (the same process ID as the thread making the call).

Native networking

MsgError() has increased latency when you use it to communicate across a network—the server is now writing the error code to its local lsm-qnet.so, which may need to communicate with the client's lsm-qnet.so to actually transfer the error code.

Returns:

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

MsgError(): If an error occurs, this function returns -1 and sets errno. Any other value returned indicates success.
MsgError_r(): If successful, this function returns EOK. This function does NOT set errno, even on success. If an error occurs, it may return any value from the Errors section.

Errors:

ESRCH: The thread indicated by rcvid doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX Neutrino

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

MsgError(), MsgError_r()