original/man3/mq_notify.3

   1 '\" t
   2 .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH MQ_NOTIFY 3 2014-04-06 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 mq_notify \- register for notification when a message is available
  29 .SH SYNOPSIS
  30 .nf
  31 .B #include <mqueue.h>
  32 .sp
  33 .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
  34 .fi
  35 .sp
  36 Link with \fI\-lrt\fP.
  37 .SH DESCRIPTION
  38 .BR mq_notify ()
  39 allows the calling process to register or unregister for delivery of
  40 an asynchronous notification when a new message arrives on
  41 the empty message queue referred to by the descriptor
  42 .IR mqdes .
  43
  44 The
  45 .I sevp
  46 argument is a pointer to a
  47 .I sigevent
  48 structure.
  49 For the definition and general details of this structure, see
  50 .BR sigevent (7).
  51 .PP
  52 If
  53 .I sevp
  54 is a non-null pointer, then
  55 .BR mq_notify ()
  56 registers the calling process to receive message notification.
  57 The
  58 .I sigev_notify
  59 field of the
  60 .I sigevent
  61 structure to which
  62 .I sevp
  63 points specifies how notification is to be performed.
  64 This field has one of the following values:
  65 .TP
  66 .B SIGEV_NONE
  67 A "null" notification: the calling process is registered as the target
  68 for notification, but when a message arrives, no notification is sent.
  69 .\" When is SIGEV_NONE useful?
  70 .TP
  71 .B SIGEV_SIGNAL
  72 Notify the process by sending the signal specified in
  73 .IR sigev_signo .
  74 See
  75 .BR sigevent (7)
  76 for general details.
  77 The
  78 .I si_code
  79 field of the
  80 .I siginfo_t
  81 structure will be set to
  82 .BR SI_MESGQ .
  83 In addition,
  84 .\" I don't know of other implementations that set
  85 .\" si_pid and si_uid -- MTK
  86 .I si_pid
  87 will be set to the PID of the process that sent the message, and
  88 .I si_uid
  89 will be set to the real user ID of the sending process.
  90 .TP
  91 .B SIGEV_THREAD
  92 Upon message delivery, invoke
  93 .I sigev_notify_function
  94 as if it were the start function of a new thread.
  95 See
  96 .BR sigevent (7)
  97 for details.
  98 .PP
  99 Only one process can be registered to receive notification
 100 from a message queue.
 101
 102 If
 103 .I sevp
 104 is NULL, and the calling process is currently registered to receive
 105 notifications for this message queue, then the registration is removed;
 106 another process can then register to receive a message notification
 107 for this queue.
 108
 109 Message notification occurs only when a new message arrives and
 110 the queue was previously empty.
 111 If the queue was not empty at the time
 112 .BR mq_notify ()
 113 was called, then a notification will occur only after
 114 the queue is emptied and a new message arrives.
 115
 116 If another process or thread is waiting to read a message
 117 from an empty queue using
 118 .BR mq_receive (3),
 119 then any message notification registration is ignored:
 120 the message is delivered to the process or thread calling
 121 .BR mq_receive (3),
 122 and the message notification registration remains in effect.
 123
 124 Notification occurs once: after a notification is delivered,
 125 the notification registration is removed,
 126 and another process can register for message notification.
 127 If the notified process wishes to receive the next notification,
 128 it can use
 129 .BR mq_notify ()
 130 to request a further notification.
 131 This should be done before emptying all unread messages from the queue.
 132 (Placing the queue in nonblocking mode is useful for emptying
 133 the queue of messages without blocking once it is empty.)
 134 .SH RETURN VALUE
 135 On success
 136 .BR mq_notify ()
 137 returns 0; on error, \-1 is returned, with
 138 .I errno
 139 set to indicate the error.
 140 .SH ERRORS
 141 .TP
 142 .B EBADF
 143 The descriptor specified in
 144 .I mqdes
 145 is invalid.
 146 .TP
 147 .B EBUSY
 148 Another process has already registered to receive notification
 149 for this message queue.
 150 .TP
 151 .B EINVAL
 152 .I sevp\->sigev_notify
 153 is not one of the permitted values; or
 154 .I sevp\->sigev_notify
 155 is
 156 .B SIGEV_SIGNAL
 157 and
 158 .I sevp\->sigev_signo
 159 is not a valid signal number.
 160 .TP
 161 .B ENOMEM
 162 Insufficient memory.
 163 .PP
 164 POSIX.1-2008 says that an implementation
 165 .I may
 166 generate an
 167 .B EINVAL
 168 .\" Linux does not do this
 169 error if
 170 .I sevp
 171 is NULL, and the caller is not currently registered to receive
 172 notifications for the queue
 173 .IR mqdes .
 174 .SH CONFORMING TO
 175 POSIX.1-2001.
 176 .SH EXAMPLE
 177 The following program registers a notification request for the
 178 message queue named in its command-line argument.
 179 Notification is performed by creating a thread.
 180 The thread executes a function which reads one message from the
 181 queue and then terminates the process.
 182 .SS Program source
 183 .nf
 184 #include <pthread.h>
 185 #include <mqueue.h>
 186 #include <stdio.h>
 187 #include <stdlib.h>
 188 #include <unistd.h>
 189
 190 #define handle_error(msg) \\
 191     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 192
 193 static void                     /* Thread start function */
 194 tfunc(union sigval sv)
 195 {
 196     struct mq_attr attr;
 197     ssize_t nr;
 198     void *buf;
 199     mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
 200
 201     /* Determine max. msg size; allocate buffer to receive msg */
 202
 203     if (mq_getattr(mqdes, &attr) == \-1)
 204         handle_error("mq_getattr");
 205     buf = malloc(attr.mq_msgsize);
 206     if (buf == NULL)
 207         handle_error("malloc");
 208
 209     nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
 210     if (nr == \-1)
 211         handle_error("mq_receive");
 212
 213     printf("Read %zd bytes from MQ\\n", nr);
 214     free(buf);
 215     exit(EXIT_SUCCESS);         /* Terminate the process */
 216 }
 217
 218 int
 219 main(int argc, char *argv[])
 220 {
 221     mqd_t mqdes;
 222     struct sigevent sev;
 223
 224     if (argc != 2) {
 225         fprintf(stderr, "Usage: %s <mq\-name>\\n", argv[0]);
 226         exit(EXIT_FAILURE);
 227     }
 228
 229     mqdes = mq_open(argv[1], O_RDONLY);
 230     if (mqdes == (mqd_t) \-1)
 231         handle_error("mq_open");
 232
 233     sev.sigev_notify = SIGEV_THREAD;
 234     sev.sigev_notify_function = tfunc;
 235     sev.sigev_notify_attributes = NULL;
 236     sev.sigev_value.sival_ptr = &mqdes;   /* Arg. to thread func. */
 237     if (mq_notify(mqdes, &sev) == \-1)
 238         handle_error("mq_notify");
 239
 240     pause();    /* Process will be terminated by thread function */
 241 }
 242 .fi
 243 .SH SEE ALSO
 244 .BR mq_close (3),
 245 .BR mq_getattr (3),
 246 .BR mq_open (3),
 247 .BR mq_receive (3),
 248 .BR mq_send (3),
 249 .BR mq_unlink (3),
 250 .BR mq_overview (7),
 251 .BR sigevent (7)
 252 .SH COLOPHON
 253 This page is part of release 3.79 of the Linux
 254 .I man-pages
 255 project.
 256 A description of the project,
 257 information about reporting bugs,
 258 and the latest version of this page,
 259 can be found at
 260 \%http://www.kernel.org/doc/man\-pages/.