manual/LDP_man-pages/original/man3/mq_send.3

   1 '\" t
   2 .\" Hey Emacs! This file is -*- nroff -*- source.
   3 .\"
   4 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .TH MQ_SEND 3 2010-02-25 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mq_send, mq_timedsend \- send a message to a message queue
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <mqueue.h>
  32 .sp
  33 .BI "mqd_t mq_send(mqd_t " mqdes ", const char *" msg_ptr ,
  34 .BI "              size_t " msg_len ", unsigned " msg_prio );
  35 .sp
  36 .B #define _XOPEN_SOURCE 600
  37 .B #include <time.h>
  38 .B #include <mqueue.h>
  39 .sp
  40 .BI "mqd_t mq_timedsend(mqd_t " mqdes ", const char *" msg_ptr ,
  41 .BI "              size_t " msg_len ", unsigned " msg_prio ,
  42 .BI "              const struct timespec *" abs_timeout );
  43 .fi
  44 .sp
  45 Link with \fI\-lrt\fP.
  46 .SH DESCRIPTION
  47 .BR mq_send ()
  48 adds the message pointed to by
  49 .I msg_ptr
  50 to the message queue referred to by the descriptor
  51 .IR mqdes .
  52 The
  53 .I msg_len
  54 argument specifies the length of the message pointed to by
  55 .IR msg_ptr ;
  56 this length must be less than or equal to the queue's
  57 .I mq_msgsize
  58 attribute.
  59 Zero-length messages are allowed.
  60
  61 The
  62 .I msg_prio
  63 argument is a nonnegative integer that specifies the priority
  64 of this message.
  65 Messages are placed on the queue in decreasing order of priority,
  66 with newer messages of the same priority being placed after
  67 older messages with the same priority.
  68
  69 If the message queue is already full
  70 (i.e., the number of messages on the queue equals the queue's
  71 .I mq_maxmsg
  72 attribute), then, by default,
  73 .BR mq_send ()
  74 blocks until sufficient space becomes available to allow the message
  75 to be queued, or until the call is interrupted by a signal handler.
  76 If the
  77 .B O_NONBLOCK
  78 flag is enabled for the message queue description,
  79 then the call instead fails immediately with the error
  80 .BR EAGAIN .
  81
  82 .BR mq_timedsend ()
  83 behaves just like
  84 .BR mq_send (),
  85 except that if the queue is full and the
  86 .B O_NONBLOCK
  87 flag is not enabled for the message queue description, then
  88 .I abs_timeout
  89 points to a structure which specifies a ceiling on the time for which
  90 the call will block.
  91 This ceiling is an absolute timeout in seconds and nanoseconds
  92 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC), and it is
  93 specified in the following structure:
  94 .sp
  95 .in +4n
  96 .nf
  97 struct timespec {
  98     time_t tv_sec;        /* seconds */
  99     long   tv_nsec;       /* nanoseconds */
 100 };
 101
 102 .fi
 103 .in
 104 If the message queue is full,
 105 and the timeout has already expired by the time of the call,
 106 .BR mq_timedsend ()
 107 returns immediately.
 108 .SH RETURN VALUE
 109 On success,
 110 .BR mq_send ()
 111 and
 112 .BR mq_timedsend ()
 113 return zero; on error, \-1 is returned, with
 114 .I errno
 115 set to indicate the error.
 116 .SH ERRORS
 117 .TP
 118 .B EAGAIN
 119 The queue was empty, and the
 120 .B O_NONBLOCK
 121 flag was set for the message queue description referred to by
 122 .IR mqdes .
 123 .TP
 124 .B EBADF
 125 The descriptor specified in
 126 .I mqdes
 127 was invalid.
 128 .TP
 129 .B EINTR
 130 The call was interrupted by a signal handler; see
 131 .BR signal (7).
 132 .TP
 133 .B EINVAL
 134 The call would have blocked, and
 135 .I abs_timeout
 136 was invalid, either because
 137 .I tv_sec
 138 was less than zero, or because
 139 .I tv_nsec
 140 was less than zero or greater than 1000 million.
 141 .TP
 142 .B EMSGSIZE
 143 .I msg_len
 144 was greater than the
 145 .I mq_msgsize
 146 attribute of the message queue.
 147 .TP
 148 .B ETIMEDOUT
 149 The call timed out before a message could be transferred.
 150 .SH CONFORMING TO
 151 POSIX.1-2001.
 152 .SH NOTES
 153 On Linux,
 154 .BR mq_timedsend ()
 155 is a system call, and
 156 .BR mq_send ()
 157 is a library function layered on top of that system call.
 158 .SH "SEE ALSO"
 159 .BR mq_close (3),
 160 .BR mq_getattr (3),
 161 .BR mq_notify (3),
 162 .BR mq_open (3),
 163 .BR mq_receive (3),
 164 .BR mq_unlink (3),
 165 .BR feature_test_macros (7),
 166 .BR mq_overview (7),
 167 .BR time (7)