Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
| z/OS® UNIX |
both |
OS/390 V2R10
|
Format
#define _OPEN_SYS_TIMED_EXT 1
#include <time.h>
#include <sys/msg.h>
int __msgrcv_timed(int msgid, void *msgp, size_t msgsz,
long int msgtyp, int msgflg, struct timespec *set);
General description
Reads a message from
the queue associated with the message queue identifier specified by msgid and
places it in the user-defined buffer pointed to by msgp.
The
argument
msgp points to a user-defined buffer
that must contain first a field of type long int that will specify
the type of the message, and then a data portion that will hold the
data bytes of the message. The structure below is an example of what
this user-defined buffer should look like:
struct message {
long int mtype; Message type
int mtext[n]; Message text
}
The structure member, mtype,
is the received message's type as specified by the sending process.
The structure member, mtext, is the text of the
message.
The argument msgsz specifies
the size in bytes of mtext. The received message
is truncated to msgsz bytes if it is larger
than msgsz and the MSG_NOERROR flag
was specified in the argument msgflg. The
truncated portion of the message is lost and no indication of the
truncation is given to the calling process.
The argument
msgtyp specifies
the type of message requested, as follows:
- If msgtyp is equal to zero, the first
message on the queue is received.
- If msgtyp is greater than 0, the first
message of type, msgtyp, is received.
- If msgtyp is less than 0, the first
message of the lowest type that is less than or equal to the absolute
value of msgtyp is received.
The argument msgflg specifies
the action to be taken if a message of the desired type is not on
the queue. These are as follows:
The argument
set is
the timespec structure which contains the timeout value.
- If the IPC_NOWAIT flag is on in msgflg,
the calling process will return immediately with a return value of
-1 and errno set to ENOMSG.
- If the IPC_NOWAIT flag is off in msgflg the
calling process will suspend execution until one of the following
occurs:
- A message of the desired type is placed on the queue.
- The message queue identifier, msgid,
is removed from the system; when this occurs, errno is set to EIDRM
and a value of -1 is returned.
- The calling process receives a signal that is to be caught; in
this case a message is not received and the calling process resumes
execution. A value of -1 is returned and errno is set to EINTR.
If successful, the following actions are taken with respect
to the data structure,
msqid_ds, associated with
msgid:
- msg_qnum is decremented by 1.
- msg_lrpid is set equal to the process ID of the
calling process.
- msg_rtime is set equal to the current time.
The variable
set gives the
timeout specification.
- If the __msgrcv_timed() function finds that none of the messages
specified by msgid are received, it waits
for the time interval specified in the timespec structure referenced
by set. If the timespec structure
pointed to by set is zero-valued and if
none of the messages specified by msgid are
received, then __msgrcv_timed() returns immediately with EAGAIN.
A timespec with the tv_sec field set with INT_MAX,
as defined in <limits.h>, will cause the __msgrcv_timed() service
to wait until a message is received. If set is
the NULL pointer, it will be treated the same as when timespec structure
was supplied with the tv_sec field set with INT_MAX.
Returned value
If successful, __msgrcv_timed()
returns a value equal to the number of bytes actually placed into
the mtext field of the user-defined buffer pointed
to by msgp. A value of zero indicates that
only the mtype field was received from the message
queue.
If unsuccessful, __msgrcv_timed() returns -1 and sets
errno to one of the following values:
- Error Code
- Description
- E2BIG
- The value of mtext is greater than msgsz and
the flag MSG_NOERROR was not specified.
- EACCES
- The calling process does not have read permission to the message
queue associated with the message queue identifier msgid.
- EAGAIN
- The operation would result in time requested expired before any
messages were received. This would result if the timeout specified
expires before a message is posted.
- EIDRM
- The message queue identifier, msgid,
has been removed from the system while the caller of __msgrcv_timed()
was waiting.
- EINTR
- The function __msgrcv_timed() was interrupted by a signal before
a message could be received.
- EINVAL
- The value of argument msgid is not a
valid message queue identifier or the value of msgsz is
less than zero.
- ENOMSG
- The flag IPC_NOWAIT was specified and the message queue
does not contain a message of the desired type.