NAME
msgsnd —
send a message to a message
queue
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/msg.h>
int
msgsnd(
int
msqid,
const void
*msgp,
size_t msgsz,
int msgflg);
DESCRIPTION
The
msgsnd() function sends a message from the message queue
specified in
msqid. The
msgp
argument is a pointer to a user-defined structure containing the message. This
structure must contain a first field of type
long that
will indicate the user-defined type of the message. The remaining fields will
contain the contents of the message. The following is an example of what this
user-defined structure might look like:
struct mymsg {
long mtype; /* message type */
char mtext[1]; /* body of message */
};
The
mtype field is an integer greater than 0 that can be
used for selecting messages (see
msgrcv(2)). The
mtext field is an array of bytes of length
msgsz, with size up to the system limit
MSGMAX
.
If the number of bytes already on the message queue plus
msgsz is greater than the maximum number of bytes in the
message queue (
msg_qbytes, see
msgctl(2)), or if the number of
messages on all queues system-wide is already equal to the system limit,
msgflg determines the action of
msgsnd(). If
msgflg has
IPC_NOWAIT
mask set in it, the call will return
immediately. If
msgflg does not have
IPC_NOWAIT
set in it, the call will block until:
- The condition which caused the call to block no longer
exists. The message was sent.
- The message queue is removed, in which case -1 will be
returned and errno set to
EINVAL
.
- The caller catches a signal. The call returns with
errno set to
EINTR
.
After a successful call, the data structure associated with the message queue is
updated in the following way:
- msg_qnum is incremented by 1.
- msg_lspid is set to the pid of the
calling process.
- msg_stime is set to the current
time.
RETURN VALUES
Upon successful completion, 0 is returned. Otherwise, -1 is returned and
errno is set to indicate the error.
ERRORS
msgsnd() will fail if:
-
-
- [
EACCES
]
- The calling process does not have write access to the
message queue.
-
-
- [
EAGAIN
]
- There was no space for this message either on the queue or
in the whole system, and
IPC_NOWAIT
was set in
msgflg.
-
-
- [
EFAULT
]
- msgp points to an invalid
address.
-
-
- [
EINTR
]
- The system call was interrupted by the delivery of a
signal.
-
-
- [
EINVAL
]
- The msqid argument is not a valid
message queue identifier, or the value of mtype is
less than 1.
The message queue was removed while msgsnd() was waiting
for a resource to become available in order to deliver the message.
The msgsz argument is greater than
msg_qbytes or
SSIZE_MAX
.
SEE ALSO
msgctl(2),
msgget(2),
msgrcv(2)
STANDARDS
The
msgsnd system call conforms to
X/Open
System Interfaces and Headers Issue 5 (“XSH5”) and
IEEE Std 1003.1-2001 (“POSIX.1”).
HISTORY
Message queues appeared in the first release of
AT&T
System V UNIX.