mirror of https://github.com/mkerrisk/man-pages
167 lines
6.1 KiB
Plaintext
167 lines
6.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "MQ_SEND" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" mq_send
|
|
.SH NAME
|
|
mq_send, mq_timedsend \- send a message to a message queue (\fBREALTIME\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <mqueue.h>
|
|
.br
|
|
.sp
|
|
int mq_send(mqd_t\fP \fImqdes\fP\fB, const char *\fP\fImsg_ptr\fP\fB,
|
|
size_t\fP \fImsg_len\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ unsigned\fP \fImsg_prio\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
.sp
|
|
\fP
|
|
.LP
|
|
\fB
|
|
.br
|
|
#include <mqueue.h>
|
|
.br
|
|
#include <time.h>
|
|
.br
|
|
int mq_timedsend(mqd_t\fP \fImqdes\fP\fB, const char *\fP\fImsg_ptr\fP\fB,
|
|
size_t\fP \fImsg_len\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ unsigned\fP \fImsg_prio\fP\fB, const struct timespec
|
|
*\fP\fIabs_timeout\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fImq_send\fP() function shall add the message pointed to by the
|
|
argument \fImsg_ptr\fP to the message queue specified by
|
|
\fImqdes\fP. The \fImsg_len\fP argument specifies the length of the
|
|
message, in bytes, pointed to by \fImsg_ptr\fP. The value of
|
|
\fImsg_len\fP shall be less than or equal to the \fImq_msgsize\fP
|
|
attribute of the message queue, or \fImq_send\fP() shall
|
|
fail.
|
|
.LP
|
|
If the specified message queue is not full, \fImq_send\fP() shall
|
|
behave as if the message is inserted into the message queue
|
|
at the position indicated by the \fImsg_prio\fP argument. A message
|
|
with a larger numeric value of \fImsg_prio\fP shall be
|
|
inserted before messages with lower values of \fImsg_prio\fP. A message
|
|
shall be inserted after other messages in the queue, if
|
|
any, with equal \fImsg_prio\fP. The value of \fImsg_prio\fP shall
|
|
be less than {MQ_PRIO_MAX}.
|
|
.LP
|
|
If the specified message queue is full and O_NONBLOCK is not set in
|
|
the message queue description associated with \fImqdes\fP,
|
|
\fImq_send\fP() shall block until space becomes available to enqueue
|
|
the message, or until \fImq_send\fP() is interrupted by a
|
|
signal. If more than one thread is waiting to send when space becomes
|
|
available in the message queue and the Priority Scheduling
|
|
option is supported, then the thread of the highest priority that
|
|
has been waiting the longest shall be unblocked to send its
|
|
message. Otherwise, it is unspecified which waiting thread is unblocked.
|
|
If the specified message queue is full and O_NONBLOCK is
|
|
set in the message queue description associated with \fImqdes\fP,
|
|
the message shall not be queued and \fImq_send\fP() shall
|
|
return an error.
|
|
.LP
|
|
The \fImq_timedsend\fP() function shall add a message to the message
|
|
queue specified by \fImqdes\fP in the manner defined for the
|
|
\fImq_send\fP() function. However, if the specified message queue
|
|
is full and O_NONBLOCK is not set in the message queue
|
|
description associated with \fImqdes\fP, the wait for sufficient room
|
|
in the queue shall be terminated when the specified timeout
|
|
expires. If O_NONBLOCK is set in the message queue description, this
|
|
function shall be equivalent to \fImq_send\fP().
|
|
.LP
|
|
The timeout shall expire when the absolute time specified by \fIabs_timeout\fP
|
|
passes, as measured by the clock on which
|
|
timeouts are based (that is, when the value of that clock equals or
|
|
exceeds \fIabs_timeout\fP), or if the absolute time specified
|
|
by \fIabs_timeout\fP has already been passed at the time of the call.
|
|
.LP
|
|
If the Timers option is supported, the timeout shall be based on the
|
|
CLOCK_REALTIME clock; if the Timers option is not
|
|
supported, the timeout shall be based on the system clock as returned
|
|
by the \fItime\fP()
|
|
function.
|
|
.LP
|
|
The resolution of the timeout shall be the resolution of the clock
|
|
on which it is based. The \fItimespec\fP argument is defined in
|
|
the \fI<time.h>\fP header.
|
|
.LP
|
|
Under no circumstance shall the operation fail with a timeout if there
|
|
is sufficient room in the queue to add the message
|
|
immediately. The validity of the \fIabs_timeout\fP parameter need
|
|
not be checked when there is sufficient room in the queue.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the \fImq_send\fP() \ and \fImq_timedsend\fP()
|
|
functions shall return a value of zero. Otherwise, no message shall
|
|
be enqueued, the functions shall
|
|
return -1, and \fIerrno\fP shall be set to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fImq_send\fP() \ and \fImq_timedsend\fP()
|
|
functions shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The O_NONBLOCK flag is set in the message queue description associated
|
|
with \fImqdes\fP, and the specified message queue is
|
|
full.
|
|
.TP 7
|
|
.B EBADF
|
|
The \fImqdes\fP argument is not a valid message queue descriptor open
|
|
for writing.
|
|
.TP 7
|
|
.B EINTR
|
|
A signal interrupted the call to \fImq_send\fP() \ or \fImq_timedsend\fP().
|
|
.TP 7
|
|
.B EINVAL
|
|
The value of \fImsg_prio\fP was outside the valid range.
|
|
.TP 7
|
|
.B EINVAL
|
|
The process or thread would have blocked, and the \fIabs_timeout\fP
|
|
parameter specified a nanoseconds field value less than zero
|
|
or greater than or equal to 1000 million.
|
|
.TP 7
|
|
.B EMSGSIZE
|
|
The specified message length, \fImsg_len\fP, exceeds the message size
|
|
attribute of the message queue.
|
|
.TP 7
|
|
.B ETIMEDOUT
|
|
The O_NONBLOCK flag was not set when the message queue was opened,
|
|
but the timeout expired before the message could be added to the
|
|
queue.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The value of the symbol {MQ_PRIO_MAX} limits the number of priority
|
|
levels supported by the application. Message priorities
|
|
range from 0 to {MQ_PRIO_MAX}-1.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fImq_open\fP() , \fImq_receive\fP() , \fImq_setattr\fP() , \fImq_timedreceive\fP()
|
|
, \fItime\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<mqueue.h>\fP, \fI<time.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|