diff options
Diffstat (limited to 'man3p/mq_send.3p')
| -rw-r--r-- | man3p/mq_send.3p | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/man3p/mq_send.3p b/man3p/mq_send.3p new file mode 100644 index 000000000..b8d1fba40 --- /dev/null +++ b/man3p/mq_send.3p @@ -0,0 +1,166 @@ +.\" 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 . |