msgsnd
Purpose
Sends a message.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgsnd (msqid, msgp, msgsz, msgflg)
int msqid;
struct msgbuf *msgp;
int msgsz, msgflg;
Description
The msgsnd system call sends a message to the queue spec-
ified by the msqid parameter. If Distributed Services is
installed on your system, this queue can reside on
another node. The current process must have write per-
mission in order to perform this operation. The msgp
parameter points to a msgbuf structure containing the
message. The msgbuf structure is defined in the
sys/msg.h header file, and it contains the following
members:
long mtype; /* Message type */
char mtext[1]; /* Beginning of message text */
The mtype parameter is a positive integer that is used by
the receiving process for message selection. The mtext
parameter is any text of the length in bytes specified by
the msgsz parameter. The msgsz parameter can range from 0
to a system-imposed maximum.
If msqid identifies a queue header that is a local key
for a remote queue, then the message is sent to the
message queue at the remote node.
The msgflg parameter specifies the action to be taken if
the message cannot be sent for one of the following
reasons:
o The number of bytes already on the queue is equal to
msg_qbytes.
o The total number of messages on all queues system-
wide is equal to a system-imposed limit.
These actions are as follows:
o If msgflg is set to IPC_NOWAIT, then the message is
not sent, and msgsnd returns a value of -1 and sets
errno to EAGAIN.
o If msgflg is 0, then the calling process suspends
execution until one of the following occurs:
- The condition responsible for the suspension no
longer exists, in which case the message is sent.
- msqid is removed from the system. (For informa-
tion on how to remove msqid, see "msgctl.") When
this occurs, errno is set equal to EIDRM, and a
value of -1 is returned.
- The calling process receives a signal that is to
be caught. In this case the message is not sent
and the calling process resumes execution in the
manner prescribed in "signal."
Return Value
Upon successful completion, a value of 0 is returned and
the following actions are taken with respect to the data
structure associated with the msqid parameter:
o msg_qnum is incremented by 1.
o msg_lspid is set equal to the process ID of the
calling process.
o msg_stime is set equal to the current time.
If the msgsnd system call fails, a value of -1 is
returned and errno is set to indicate the error.
Diagnostics
The msgsnd system call fails and no message is sent if
one or more of the following are true:
EINVAL The msqid parameter is not a valid message
queue identifier.
EACCES Operation permission is denied to the calling
process.
EINVAL mtype is less than 1.
EAGAIN The message cannot be sent for one of the
reasons stated previously, and msgflg is set
to IPC_NOWAIT.
EINVAL The msgsz parameter is less than 0 or greater
than the system-imposed limit.
EFAULT The msgp parameter &pointsout..
EINTR msgsnd received a signal.
EIDRM The message queue identifier specified by
msqid has been removed from the system.
If Distributed Services is installed on your system,
msgsnd can also fail if one or more of the following are
true:
ESTALE The current boot count of the server is the
same as when the msqid was obtained.
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "msgctl," "msgget," "msgrcv," "msgxrcv,"
and "signal."