summaryrefslogtreecommitdiffstats
path: root/man3/mq_send.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/mq_send.3171
1 files changed, 171 insertions, 0 deletions
diff --git a/man3/mq_send.3 b/man3/mq_send.3
new file mode 100644
index 0000000..7e1b6c6
--- /dev/null
+++ b/man3/mq_send.3
@@ -0,0 +1,171 @@
+'\" t
+.\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH mq_send 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+mq_send, mq_timedsend \- send a message to a message queue
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B #include <mqueue.h>
+.PP
+.BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
+.BI " size_t " msg_len ", unsigned int " msg_prio );
+.PP
+.B #include <time.h>
+.B #include <mqueue.h>
+.PP
+.BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
+.BI " size_t " msg_len ", unsigned int " msg_prio ,
+.BI " const struct timespec *" abs_timeout );
+.fi
+.PP
+.ad l
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR mq_timedsend ():
+.nf
+ _POSIX_C_SOURCE >= 200112L
+.fi
+.SH DESCRIPTION
+.BR mq_send ()
+adds the message pointed to by
+.I msg_ptr
+to the message queue referred to by the message queue descriptor
+.IR mqdes .
+The
+.I msg_len
+argument specifies the length of the message pointed to by
+.IR msg_ptr ;
+this length must be less than or equal to the queue's
+.I mq_msgsize
+attribute.
+Zero-length messages are allowed.
+.PP
+The
+.I msg_prio
+argument is a nonnegative integer that specifies the priority
+of this message.
+Messages are placed on the queue in decreasing order of priority,
+with newer messages of the same priority being placed after
+older messages with the same priority.
+See
+.BR mq_overview (7)
+for details on the range for the message priority.
+.PP
+If the message queue is already full
+(i.e., the number of messages on the queue equals the queue's
+.I mq_maxmsg
+attribute), then, by default,
+.BR mq_send ()
+blocks until sufficient space becomes available to allow the message
+to be queued, or until the call is interrupted by a signal handler.
+If the
+.B O_NONBLOCK
+flag is enabled for the message queue description,
+then the call instead fails immediately with the error
+.BR EAGAIN .
+.PP
+.BR mq_timedsend ()
+behaves just like
+.BR mq_send (),
+except that if the queue is full and the
+.B O_NONBLOCK
+flag is not enabled for the message queue description, then
+.I abs_timeout
+points to a structure which specifies how long the call will block.
+This value is an absolute timeout in seconds and nanoseconds
+since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
+specified in a
+.BR timespec (3)
+structure.
+.PP
+If the message queue is full,
+and the timeout has already expired by the time of the call,
+.BR mq_timedsend ()
+returns immediately.
+.SH RETURN VALUE
+On success,
+.BR mq_send ()
+and
+.BR mq_timedsend ()
+return zero; on error, \-1 is returned, with
+.I errno
+set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The queue was full, and the
+.B O_NONBLOCK
+flag was set for the message queue description referred to by
+.IR mqdes .
+.TP
+.B EBADF
+The descriptor specified in
+.I mqdes
+was invalid or not opened for writing.
+.TP
+.B EINTR
+The call was interrupted by a signal handler; see
+.BR signal (7).
+.TP
+.B EINVAL
+The call would have blocked, and
+.I abs_timeout
+was invalid, either because
+.I tv_sec
+was less than zero, or because
+.I tv_nsec
+was less than zero or greater than 1000 million.
+.TP
+.B EMSGSIZE
+.I msg_len
+was greater than the
+.I mq_msgsize
+attribute of the message queue.
+.TP
+.B ETIMEDOUT
+The call timed out before a message could be transferred.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR mq_send (),
+.BR mq_timedsend ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH VERSIONS
+On Linux,
+.BR mq_timedsend ()
+is a system call, and
+.BR mq_send ()
+is a library function layered on top of that system call.
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH SEE ALSO
+.BR mq_close (3),
+.BR mq_getattr (3),
+.BR mq_notify (3),
+.BR mq_open (3),
+.BR mq_receive (3),
+.BR mq_unlink (3),
+.BR timespec (3),
+.BR mq_overview (7),
+.BR time (7)