original/man3/mq_notify.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_NOTIFY 3 2009-09-15 "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 "mqd_t mq_notify(mqd_t " mqdes ", const struct sigevent *" notification );
  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 notification
  46 argument is a pointer to a
  47 .I sigevent
  48 structure that is defined something like the following:
  49 .in +4n
  50 .nf
  51
  52 union sigval {          /* Data passed with notification */
  53     int     sival_int;         /* Integer value */
  54     void   *sival_ptr;         /* Pointer value */
  55 };
  56
  57 struct sigevent {
  58     int          sigev_notify; /* Notification method */
  59     int          sigev_signo;  /* Notification signal */
  60     union sigval sigev_value;  /* Data passed with
  61                                   notification */
  62     void       (*sigev_notify_function) (union sigval);
  63                                /* Function for thread
  64                                   notification */
  65     void        *sigev_notify_attributes;
  66                                /* Thread function attributes */
  67 };
  68 .fi
  69 .in
  70 .PP
  71 If
  72 .I notification
  73 is a non-NULL pointer, then
  74 .BR mq_notify ()
  75 registers the calling process to receive message notification.
  76 The
  77 .I sigev_notify
  78 field of the
  79 .I sigevent
  80 to which
  81 .I notification
  82 points specifies how notification is to be performed.
  83 This field has one of the following values:
  84 .TP
  85 .B SIGEV_NONE
  86 A "null" notification: the calling process is registered as the target
  87 for notification, but when a message arrives, no notification is sent.
  88 .\" When is SIGEV_NONE useful?
  89 .TP
  90 .B SIGEV_SIGNAL
  91 Notify the process by sending the signal specified in
  92 .IR sigev_signo .
  93 If the signal is caught with a signal handler that
  94 was registered using the
  95 .BR sigaction (2)
  96 .B SA_SIGINFO
  97 flag, then the following fields are set in the
  98 .I siginfo_t
  99 structure that is passed as the second argument of the handler:
 100 .I si_code
 101 is set to
 102 .BR SI_MESGQ ;
 103 .I si_signo
 104 is set to the signal number;
 105 .I si_value
 106 is set to the value specified in
 107 .IR notification\->sigev_value ;
 108 .\" I don't know of other implementations that set
 109 .\" si_pid and si_uid -- MTK
 110 .I si_pid
 111 is set to the PID of the process that sent the message; and
 112 .I si_uid
 113 is set to the real user ID of the sending process.
 114 The same information is available if the signal is accepted using
 115 .BR sigwaitinfo (2).
 116 .TP
 117 .B SIGEV_THREAD
 118 Deliver notification by invoking
 119 .I notification\->sigev_notify_function
 120 as the start function of a new thread.
 121 The function is invoked with
 122 .I notification\->sigev_value
 123 as its sole argument.
 124 If
 125 .I notification\->sigev_notify_attributes
 126 is not NULL, then it should point to a
 127 .I pthread_attr_t
 128 structure that defines attributes for the thread (see
 129 .BR pthread_attr_init (3)).
 130 .PP
 131 Only one process can be registered to receive notification
 132 from a message queue.
 133
 134 If
 135 .I notification
 136 is NULL, and the calling process is currently registered to receive
 137 notifications for this message queue, then the registration is removed;
 138 another process can then register to receive a message notification
 139 for this queue.
 140
 141 Message notification only occurs when a new message arrives and
 142 the queue was previously empty.
 143 If the queue was not empty at the time
 144 .BR mq_notify ()
 145 was called, then a notification will only occur after
 146 the queue is emptied and a new message arrives.
 147
 148 If another process or thread is waiting to read a message
 149 from an empty queue using
 150 .BR mq_receive (3),
 151 then any message notification registration is ignored:
 152 the message is delivered to the process or thread calling
 153 .BR mq_receive (3),
 154 and the message notification registration remains in effect.
 155
 156 Notification occurs once: after a notification is delivered,
 157 the notification registration is removed,
 158 and another process can register for message notification.
 159 If the notified process wishes to receive the next notification,
 160 it can use
 161 .BR mq_notify ()
 162 to request a further notification.
 163 This should be done before emptying all unread messages from the queue.
 164 (Placing the queue in nonblocking mode is useful for emptying
 165 the queue of messages without blocking once it is empty.)
 166 .SH RETURN VALUE
 167 On success
 168 .BR mq_notify ()
 169 returns 0; on error, \-1 is returned, with
 170 .I errno
 171 set to indicate the error.
 172 .SH ERRORS
 173 .TP
 174 .B EBADF
 175 The descriptor specified in
 176 .I mqdes
 177 is invalid.
 178 .TP
 179 .B EBUSY
 180 Another process has already registered to receive notification
 181 for this message queue.
 182 .TP
 183 .B EINVAL
 184 .I notification\->sigev_notify
 185 is not one of the permitted values; or
 186 .I notification\->sigev_notify
 187 is
 188 .B SIGEV_SIGNAL
 189 and
 190 .I notification\->sigev_signo
 191 is not a valid signal number.
 192 .TP
 193 .B ENOMEM
 194 Insufficient memory.
 195 .PP
 196 POSIX.1-2008 says that an implementation
 197 .I may
 198 generate an
 199 .B EINVAL
 200 .\" Linux does not do this
 201 error if
 202 .I notification
 203 is NULL, and the caller is not currently registered to receive
 204 notifications for the queue
 205 .IR mqdes .
 206 .SH CONFORMING TO
 207 POSIX.1-2001.
 208 .SH EXAMPLE
 209 The following program registers a notification request for the
 210 message queue named in its command-line argument.
 211 Notification is performed by creating a thread.
 212 The thread executes a function which reads one message from the
 213 queue and then terminates the process.
 214 .nf
 215
 216 #include <pthread.h>
 217 #include <mqueue.h>
 218 #include <stdio.h>
 219 #include <stdlib.h>
 220 #include <unistd.h>
 221
 222 #define handle_error(msg) \\
 223     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 224
 225 static void                     /* Thread start function */
 226 tfunc(union sigval sv)
 227 {
 228     struct mq_attr attr;
 229     ssize_t nr;
 230     void *buf;
 231     mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
 232
 233     /* Determine max. msg size; allocate buffer to receive msg */
 234
 235     if (mq_getattr(mqdes, &attr) == \-1)
 236         handle_error("mq_getattr");
 237     buf = malloc(attr.mq_msgsize);
 238     if (buf == NULL)
 239         handle_error("malloc");
 240
 241     nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
 242     if (nr == \-1)
 243         handle_error("mq_receive");
 244
 245     printf("Read %ld bytes from MQ\\n", (long) nr);
 246     free(buf);
 247     exit(EXIT_SUCCESS);         /* Terminate the process */
 248 }
 249
 250 int
 251 main(int argc, char *argv[])
 252 {
 253     mqd_t mqdes;
 254     struct sigevent not;
 255
 256     if (argc != 2) {
 257         fprintf(stderr, "Usage: %s <mq-name>\\n", argv[0]);
 258         exit(EXIT_FAILURE);
 259     }
 260
 261     mqdes = mq_open(argv[1], O_RDONLY);
 262     if (mqdes == (mqd_t) \-1)
 263         handle_error("mq_open");
 264
 265     not.sigev_notify = SIGEV_THREAD;
 266     not.sigev_notify_function = tfunc;
 267     not.sigev_notify_attributes = NULL;
 268     not.sigev_value.sival_ptr = &mqdes;   /* Arg. to thread func. */
 269     if (mq_notify(mqdes, &not) == \-1)
 270         handle_error("mq_notify");
 271
 272     pause();    /* Process will be terminated by thread function */
 273 }
 274 .fi
 275 .SH "SEE ALSO"
 276 .BR mq_close (3),
 277 .BR mq_getattr (3),
 278 .BR mq_open (3),
 279 .BR mq_receive (3),
 280 .BR mq_send (3),
 281 .BR mq_unlink (3),
 282 .BR mq_overview (7)