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 2019-03-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 .PP
  33 .BI "int mq_notify(mqd_t " mqdes ", const struct sigevent *" sevp );
  34 .fi
  35 .PP
  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 message queue descriptor
  42 .IR mqdes .
  43 .PP
  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 .PP
 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 .PP
 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 .PP
 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 .PP
 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 message queue 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 ATTRIBUTES
 175 For an explanation of the terms used in this section, see
 176 .BR attributes (7).
 177 .TS
 178 allbox;
 179 lb lb lb
 180 l l l.
 181 Interface       Attribute       Value
 182 T{
 183 .BR mq_notify ()
 184 T}      Thread safety   MT-Safe
 185 .TE
 186 .sp 1
 187 .SH CONFORMING TO
 188 POSIX.1-2001.
 189 .SH NOTES
 190 .\"
 191 .SS C library/kernel differences
 192 In the glibc implementation, the
 193 .BR mq_notify ()
 194 library function is implemented on top of the system call of the same name.
 195 When
 196 .I sevp
 197 is NULL, or specifies a notification mechanism other than
 198 .BR SIGEV_THREAD ,
 199 the library function directly invokes the system call.
 200 For
 201 .BR SIGEV_THREAD ,
 202 much of the implementation resides within the library,
 203 rather than the kernel.
 204 (This is necessarily so,
 205 since the thread involved in handling the notification is one
 206 that must be managed by the C library POSIX threads implementation.)
 207 The implementation involves the use of a raw
 208 .BR netlink (7)
 209 socket and creates a new thread for each notification that is
 210 delivered to the process.
 211 .SH EXAMPLE
 212 The following program registers a notification request for the
 213 message queue named in its command-line argument.
 214 Notification is performed by creating a thread.
 215 The thread executes a function which reads one message from the
 216 queue and then terminates the process.
 217 .SS Program source
 218 .EX
 219 #include <pthread.h>
 220 #include <mqueue.h>
 221 #include <stdio.h>
 222 #include <stdlib.h>
 223 #include <unistd.h>
 224
 225 #define handle_error(msg) \e
 226     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 227
 228 static void                     /* Thread start function */
 229 tfunc(union sigval sv)
 230 {
 231     struct mq_attr attr;
 232     ssize_t nr;
 233     void *buf;
 234     mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
 235
 236     /* Determine max. msg size; allocate buffer to receive msg */
 237
 238     if (mq_getattr(mqdes, &attr) == \-1)
 239         handle_error("mq_getattr");
 240     buf = malloc(attr.mq_msgsize);
 241     if (buf == NULL)
 242         handle_error("malloc");
 243
 244     nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
 245     if (nr == \-1)
 246         handle_error("mq_receive");
 247
 248     printf("Read %zd bytes from MQ\en", nr);
 249     free(buf);
 250     exit(EXIT_SUCCESS);         /* Terminate the process */
 251 }
 252
 253 int
 254 main(int argc, char *argv[])
 255 {
 256     mqd_t mqdes;
 257     struct sigevent sev;
 258
 259     if (argc != 2) {
 260         fprintf(stderr, "Usage: %s <mq\-name>\en", argv[0]);
 261         exit(EXIT_FAILURE);
 262     }
 263
 264     mqdes = mq_open(argv[1], O_RDONLY);
 265     if (mqdes == (mqd_t) \-1)
 266         handle_error("mq_open");
 267
 268     sev.sigev_notify = SIGEV_THREAD;
 269     sev.sigev_notify_function = tfunc;
 270     sev.sigev_notify_attributes = NULL;
 271     sev.sigev_value.sival_ptr = &mqdes;   /* Arg. to thread func. */
 272     if (mq_notify(mqdes, &sev) == \-1)
 273         handle_error("mq_notify");
 274
 275     pause();    /* Process will be terminated by thread function */
 276 }
 277 .EE
 278 .SH SEE ALSO
 279 .BR mq_close (3),
 280 .BR mq_getattr (3),
 281 .BR mq_open (3),
 282 .BR mq_receive (3),
 283 .BR mq_send (3),
 284 .BR mq_unlink (3),
 285 .BR mq_overview (7),
 286 .BR sigevent (7)