Originální popis anglicky:
msgop - message operations
Návod, kniha: Linux Programmer's Manual
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgsnd(int msqid, struct msgbuf
*msgp, size_t msgsz, int
msgflg);
ssize_t msgrcv(int msqid, struct msgbuf
*msgp, size_t msgsz, long
msgtyp, int msgflg);
To send or receive a message, the calling process allocates a structure of the
following general form:
struct msgbuf {
long mtype; /* message type, must be > 0 */
char mtext[1]; /* message data */
};
The
mtext field is an array (or other structure) whose size is specified
by
msgsz, a non-negative integer value. Messages of zero length (i.e.,
no
mtext field) are permitted. The
mtype field must have a
strictly positive integer value that can be used by the receiving process for
message selection (see the section about
msgrcv).
The calling process must have write permission to send and read permission to
receive a message on the queue.
The
msgsnd system call appends a copy of the message pointed to by
msgp to the message queue whose identifier is specified by
msqid.
If sufficient space is available on the queue,
msgsnd succeeds
immediately. (The queue capacity is defined by the
msg_bytes field in
the associated data structure for the message queue. During queue creation
this field is initialised to
MSGMNB bytes, but this limit can be
modified using
msgctl.) If insufficient space is available on the
queue, then the default behaviour of
msgsnd is to block until space
becomes available. If
IPC_NOWAIT is asserted in
msgflg then the
call instead fails with the error
EAGAIN.
A blocked
msgsnd call may also fail if the queue is removed (in which
case the system call fails with
errno set to
EIDRM), or a signal
is caught (in which case the system call fails with
errno set to
EINTR). (
msgsnd and
msgrcv are never automatically
restarted after being interrupted by a signal handler, regardless of the
setting of the
SA_RESTART flag when establishing a signal handler.)
Upon successful completion the message queue data structure is updated as
follows:
- msg_lspid is set to the process ID of the calling
process.
- msg_qnum is incremented by 1.
- msg_stime is set to the current time.
The system call
msgrcv reads a message from the message queue specified
by
msqid into the
msgbuf pointed to by the
msgp argument,
removing the read message from the queue.
The argument
msgsz specifies the maximum size in bytes for the member
mtext of the structure pointed to by the
msgp argument. If the
message text has length greater than
msgsz, then if the
msgflg
argument asserts
MSG_NOERROR, the message text will be truncated (and
the truncated part will be lost), otherwise the message isn't removed from the
queue and the system call fails returning with
errno set to
E2BIG.
The argument
msgtyp specifies the type of message requested as follows:
- If msgtyp is 0, then the first message in the
queue is read.
- If msgtyp is greater than 0, then the first
message on the queue of type msgtyp is read, unless
MSG_EXCEPT was asserted in msgflg, in which case the first
message on the queue of type not equal to msgtyp will be read.
- If msgtyp is less than 0, then the first
message on the queue with the lowest type less than or equal to the
absolute value of msgtyp will be read.
The
msgflg argument asserts none, one or more (or-ing them) of the
following flags:
- IPC_NOWAIT For immediate return if no message of the
requested type is on the queue. The system call fails with errno set to
ENOMSG.
- MSG_EXCEPT Used with msgtyp greater than
0 to read the first message on the queue with message type that
differs from msgtyp.
- MSG_NOERROR To truncate the message text if longer
than msgsz bytes.
If no message of the requested type is available and
IPC_NOWAIT isn't
asserted in
msgflg, the calling process is blocked until one of the
following conditions occurs:
- A message of the desired type is placed on the queue.
- The message queue is removed from the system. In this case
the system call fails with errno set to EIDRM.
- The calling process catches a signal. In this case the
system call fails with errno set to EINTR.
Upon successful completion the message queue data structure is updated as
follows:
- msg_lrpid is set to the process ID of the calling
process.
- msg_qnum is decremented by 1.
- msg_rtime is set to the current time.
On a failure both functions return
-1 with
errno indicating the
error, otherwise
msgsnd returns
0 and
msgrvc returns the
number of bytes actually copied into the
mtext array.
When
msgsnd fails, at return
errno will be set to one among the
following values:
- EACCES
- The calling process does not have write permission on the
message queue, and does not have the CAP_IPC_OWNER capability.
- EAGAIN
- The message can't be sent due to the msg_qbytes
limit for the queue and IPC_NOWAIT was asserted in
mgsflg.
- EFAULT
- The address pointed to by msgp isn't
accessible.
- EIDRM
- The message queue was removed.
- EINTR
- Sleeping on a full message queue condition, the process
caught a signal.
- EINVAL
- Invalid msqid value, or nonpositive mtype
value, or invalid msgsz value (less than 0 or greater than the
system value MSGMAX).
- ENOMEM
- The system has not enough memory to make a copy of the
supplied msgbuf.
When
msgrcv fails, at return
errno will be set to one among the
following values:
- E2BIG
- The message text length is greater than msgsz and
MSG_NOERROR isn't asserted in msgflg.
- EACCES
- The calling process does not have read permission on the
message queue, and does not have the CAP_IPC_OWNER capability.
- EFAULT
- The address pointed to by msgp isn't
accessible.
- EIDRM
- While the process was sleeping to receive a message, the
message queue was removed.
- EINTR
- While the process was sleeping to receive a message, the
process received a signal that had to be caught.
- EINVAL
- Illegal msgqid value, or msgsz less than
0.
- ENOMSG
- IPC_NOWAIT was asserted in msgflg and no
message of the requested type existed on the message queue.
The followings are system limits affecting a
msgsnd system call:
- MSGMAX
- Maximum size for a message text: the implementation set
this value to 8192 bytes.
- MSGMNB
- Default maximum size in bytes of a message queue: 16384
bytes. The super-user can increase the size of a message queue beyond
MSGMNB by a msgctl system call.
The implementation has no intrinsic limits for the system wide maximum number of
message headers (
MSGTQL) and for the system wide maximum size in bytes
of the message pool (
MSGPOOL).
SVr4, SVID.
The pointer argument is declared as
struct msgbuf * with libc4, libc5,
glibc 2.0, glibc 2.1. It is declared as
void * (
const void *
for
msgsnd()) with glibc 2.2, following the SUSv2.
msgctl(2),
msgget(2),
msgrcv(2),
msgsnd(2),
ipc(5),
capabilities(7)
