man3/mq_notify.3

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