man3/mq_send.3

   1 '\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH mq_send 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 mq_send, mq_timedsend \- send a message to a message queue
   9 .SH LIBRARY
  10 Real-time library
  11 .RI ( librt ", " \-lrt )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <mqueue.h>
  15 .PP
  16 .BI "int mq_send(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
  17 .BI "              size_t " msg_len ", unsigned int " msg_prio );
  18 .PP
  19 .B #include <time.h>
  20 .B #include <mqueue.h>
  21 .PP
  22 .BI "int mq_timedsend(mqd_t " mqdes ", const char " msg_ptr [. msg_len ],
  23 .BI "              size_t " msg_len ", unsigned int " msg_prio ,
  24 .BI "              const struct timespec *" abs_timeout );
  25 .fi
  26 .PP
  27 .ad l
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR mq_timedsend ():
  34 .nf
  35     _POSIX_C_SOURCE >= 200112L
  36 .fi
  37 .SH DESCRIPTION
  38 .BR mq_send ()
  39 adds the message pointed to by
  40 .I msg_ptr
  41 to the message queue referred to by the message queue descriptor
  42 .IR mqdes .
  43 The
  44 .I msg_len
  45 argument specifies the length of the message pointed to by
  46 .IR msg_ptr ;
  47 this length must be less than or equal to the queue's
  48 .I mq_msgsize
  49 attribute.
  50 Zero-length messages are allowed.
  51 .PP
  52 The
  53 .I msg_prio
  54 argument is a nonnegative integer that specifies the priority
  55 of this message.
  56 Messages are placed on the queue in decreasing order of priority,
  57 with newer messages of the same priority being placed after
  58 older messages with the same priority.
  59 See
  60 .BR mq_overview (7)
  61 for details on the range for the message priority.
  62 .PP
  63 If the message queue is already full
  64 (i.e., the number of messages on the queue equals the queue's
  65 .I mq_maxmsg
  66 attribute), then, by default,
  67 .BR mq_send ()
  68 blocks until sufficient space becomes available to allow the message
  69 to be queued, or until the call is interrupted by a signal handler.
  70 If the
  71 .B O_NONBLOCK
  72 flag is enabled for the message queue description,
  73 then the call instead fails immediately with the error
  74 .BR EAGAIN .
  75 .PP
  76 .BR mq_timedsend ()
  77 behaves just like
  78 .BR mq_send (),
  79 except that if the queue is full and the
  80 .B O_NONBLOCK
  81 flag is not enabled for the message queue description, then
  82 .I abs_timeout
  83 points to a structure which specifies how long the call will block.
  84 This value is an absolute timeout in seconds and nanoseconds
  85 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC),
  86 specified in a
  87 .BR timespec (3)
  88 structure.
  89 .PP
  90 If the message queue is full,
  91 and the timeout has already expired by the time of the call,
  92 .BR mq_timedsend ()
  93 returns immediately.
  94 .SH RETURN VALUE
  95 On success,
  96 .BR mq_send ()
  97 and
  98 .BR mq_timedsend ()
  99 return zero; on error, \-1 is returned, with
 100 .I errno
 101 set to indicate the error.
 102 .SH ERRORS
 103 .TP
 104 .B EAGAIN
 105 The queue was full, and the
 106 .B O_NONBLOCK
 107 flag was set for the message queue description referred to by
 108 .IR mqdes .
 109 .TP
 110 .B EBADF
 111 The descriptor specified in
 112 .I mqdes
 113 was invalid or not opened for writing.
 114 .TP
 115 .B EINTR
 116 The call was interrupted by a signal handler; see
 117 .BR signal (7).
 118 .TP
 119 .B EINVAL
 120 The call would have blocked, and
 121 .I abs_timeout
 122 was invalid, either because
 123 .I tv_sec
 124 was less than zero, or because
 125 .I tv_nsec
 126 was less than zero or greater than 1000 million.
 127 .TP
 128 .B EMSGSIZE
 129 .I msg_len
 130 was greater than the
 131 .I mq_msgsize
 132 attribute of the message queue.
 133 .TP
 134 .B ETIMEDOUT
 135 The call timed out before a message could be transferred.
 136 .SH ATTRIBUTES
 137 For an explanation of the terms used in this section, see
 138 .BR attributes (7).
 139 .ad l
 140 .nh
 141 .TS
 142 allbox;
 143 lbx lb lb
 144 l l l.
 145 Interface       Attribute       Value
 146 T{
 147 .BR mq_send (),
 148 .BR mq_timedsend ()
 149 T}      Thread safety   MT-Safe
 150 .TE
 151 .hy
 152 .ad
 153 .sp 1
 154 .SH STANDARDS
 155 POSIX.1-2001, POSIX.1-2008.
 156 .SH NOTES
 157 On Linux,
 158 .BR mq_timedsend ()
 159 is a system call, and
 160 .BR mq_send ()
 161 is a library function layered on top of that system call.
 162 .SH SEE ALSO
 163 .BR mq_close (3),
 164 .BR mq_getattr (3),
 165 .BR mq_notify (3),
 166 .BR mq_open (3),
 167 .BR mq_receive (3),
 168 .BR mq_unlink (3),
 169 .BR timespec (3),
 170 .BR mq_overview (7),
 171 .BR time (7)