man3/mq_receive.3

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