MsgError(), MsgError_r()

Arguments:

rcvid

The receive ID that MsgReceive*() returned.

error

-1, ERESTART, EOK, or 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 usually 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.

The error argument determines how the MsgError*() kernel call affects the client's REPLY-blocked MsgSend*() call:

• Specify -1 for error only when handling an unblock pulse. Using -1 in any other case results in undefined behavior.

  When a server receives an unblock pulse, it typically can't determine why. When the server calls MsgError*() with an error of -1, it sets the client's error code to whatever error the kernel stored when the unblock pulse was sent.

  When a thread that's REPLY-blocked on a channel attempts to unblock before its message is replied to, the kernel associates one of the following error codes with the thread:

  • EINTR if the thread is waking up to run a signal handler.
  • ETIMEDOUT if the thread is waking up due to a SIGEV_UNBLOCK event.
• If error is ERESTART, the sender immediately calls MsgSend*() again. Because send and reply buffers passed to MsgSend*() may overlap, don't use ERESTART after a call to MsgWrite*().
• 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.

Blocking states

None

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 OS