1MQ_NOTIFY(3P)              POSIX Programmer's Manual             MQ_NOTIFY(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       mq_notify — notify process that a message is available (REALTIME)
13

SYNOPSIS

15       #include <mqueue.h>
16
17       int mq_notify(mqd_t mqdes, const struct sigevent *notification);
18

DESCRIPTION

20       If the argument notification is not NULL, this function shall  register
21       the  calling process to be notified of message arrival at an empty mes‐
22       sage queue associated with  the  specified  message  queue  descriptor,
23       mqdes.   The  notification specified by the notification argument shall
24       be sent to the process when the message queue transitions from empty to
25       non-empty.  At any time, only one process may be registered for notifi‐
26       cation by a message queue. If the calling process or any other  process
27       has already registered for notification of message arrival at the spec‐
28       ified message queue, subsequent attempts to register for  that  message
29       queue shall fail.
30
31       If  notification  is  NULL  and the process is currently registered for
32       notification by the specified message queue, the existing  registration
33       shall be removed.
34
35       When  the notification is sent to the registered process, its registra‐
36       tion shall be removed. The message queue shall then  be  available  for
37       registration.
38
39       If  a  process  has registered for notification of message arrival at a
40       message queue and some thread is blocked in  mq_receive()  or  mq_time‐
41       dreceive()  waiting  to receive a message when a message arrives at the
42       queue, the arriving message shall satisfy the appropriate  mq_receive()
43       or mq_timedreceive(), respectively. The resulting behavior is as if the
44       message queue remains empty, and no notification shall be sent.
45

RETURN VALUE

47       Upon successful completion, the mq_notify()  function  shall  return  a
48       value  of  zero; otherwise, the function shall return a value of -1 and
49       set errno to indicate the error.
50

ERRORS

52       The mq_notify() function shall fail if:
53
54       EBADF  The mqdes argument is not a valid message queue descriptor.
55
56       EBUSY  A process is already registered for notification by the  message
57              queue.
58
59       The mq_notify() function may fail if:
60
61       EINVAL The  notification  argument is NULL and the process is currently
62              not registered.
63
64       The following sections are informative.
65

EXAMPLES

67       The following program registers a notification request for the  message
68       queue  named in its command-line argument. Notification is performed by
69       creating a thread. The thread executes a function which reads one  mes‐
70       sage from the queue and then terminates the process.
71
72
73           #include <pthread.h>
74           #include <mqueue.h>
75           #include <assert.h>
76           #include <stdio.h>
77           #include <stdlib.h>
78           #include <unistd.h>
79
80           static void                     /* Thread start function */
81           tfunc(union sigval sv)
82           {
83               struct mq_attr attr;
84               ssize_t nr;
85               void *buf;
86               mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
87
88               /* Determine maximum msg size; allocate buffer to receive msg */
89
90               if (mq_getattr(mqdes, &attr) == -1) {
91                   perror("mq_getattr");
92                   exit(EXIT_FAILURE);
93               }
94               buf = malloc(attr.mq_msgsize);
95
96               if (buf == NULL) {
97                   perror("malloc");
98                   exit(EXIT_FAILURE);
99               }
100
101               nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
102               if (nr == -1) {
103                   perror("mq_receive");
104                   exit(EXIT_FAILURE);
105               }
106
107               printf("Read %ld bytes from message queue\n", (long) nr);
108               free(buf);
109               exit(EXIT_SUCCESS);         /* Terminate the process */
110           }
111
112           int
113           main(int argc, char *argv[])
114           {
115               mqd_t mqdes;
116               struct sigevent not;
117
118               assert(argc == 2);
119
120               mqdes = mq_open(argv[1], O_RDONLY);
121               if (mqdes == (mqd_t) -1) {
122                   perror("mq_open");
123                   exit(EXIT_FAILURE);
124               }
125
126               not.sigev_notify = SIGEV_THREAD;
127               not.sigev_notify_function = tfunc;
128               not.sigev_notify_attributes = NULL;
129               not.sigev_value.sival_ptr = &mqdes;   /* Arg. to thread func. */
130               if (mq_notify(mqdes, &not) == -1) {
131                   perror("mq_notify");
132                   exit(EXIT_FAILURE);
133               }
134
135               pause();    /* Process will be terminated by thread function */
136           }
137

APPLICATION USAGE

139       None.
140

RATIONALE

142       None.
143

FUTURE DIRECTIONS

145       None.
146

SEE ALSO

148       mq_open(),   mq_send(),  mq_receive(),  msgctl(),  msgget(),  msgrcv(),
149       msgsnd()
150
151       The Base Definitions volume of POSIX.1‐2017, <mqueue.h>
152
154       Portions of this text are reprinted and reproduced in  electronic  form
155       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
156       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
157       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
158       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
159       event of any discrepancy between this version and the original IEEE and
160       The Open Group Standard, the original IEEE and The Open Group  Standard
161       is  the  referee document. The original Standard can be obtained online
162       at http://www.opengroup.org/unix/online.html .
163
164       Any typographical or formatting errors that appear  in  this  page  are
165       most likely to have been introduced during the conversion of the source
166       files to man page format. To report such errors,  see  https://www.ker
167       nel.org/doc/man-pages/reporting_bugs.html .
168
169
170
171IEEE/The Open Group                  2017                        MQ_NOTIFY(3P)
Impressum