1.\" Copyright (c) 2005 David Xu <davidxu@FreeBSD.org> 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" Portions of this text are reprinted and reproduced in electronic form 29.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 30.\" Portable Operating System Interface (POSIX), The Open Group Base 31.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 32.\" Electrical and Electronics Engineers, Inc and The Open Group. In the 33.\" event of any discrepancy between this version and the original IEEE and 34.\" The Open Group Standard, the original IEEE and The Open Group Standard is 35.\" the referee document. The original Standard can be obtained online at 36.\" http://www.opengroup.org/unix/online.html. 37.\" 38.Dd July 15, 2016 39.Dt MQ_NOTIFY 2 40.Os 41.Sh NAME 42.Nm mq_notify 43.Nd "notify process that a message is available (REALTIME)" 44.Sh LIBRARY 45.Lb librt 46.Sh SYNOPSIS 47.In mqueue.h 48.Ft int 49.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" 50.Sh DESCRIPTION 51If the argument notification is not 52.Dv NULL , 53this system call will register the calling process to be notified of message 54arrival at an empty message queue associated with the specified message 55queue descriptor, 56.Fa mqdes . 57The notification specified by the 58.Fa notification 59argument will be sent to 60the process when the message queue transitions from empty to non-empty. 61At any time, only one process may be registered for notification by a 62message queue. 63If the calling process or any other process has already 64registered for notification of message arrival at the specified message 65queue, subsequent attempts to register for that message queue will fail. 66.Pp 67The 68.Fa notification 69argument points to a 70.Vt sigevent 71structure that defines how the calling process will be notified. 72If 73.Fa notification->sigev_notify 74is 75.Dv SIGEV_NONE , 76then no signal will be posted, but the error status and the return status 77for the operation will be set appropriately. 78For 79.Dv SIGEV_SIGNO 80and 81.Dv SIGEV_THREAD_ID 82notifications, 83the signal specified in 84.Fa notification->sigev_signo 85will be sent to the calling process 86.Pq Dv SIGEV_SIGNO 87or to the thread whose LWP ID is 88.Fa notification->sigev_notify_thread_id 89.Pq Dv SIGEV_THREAD_ID . 90The information for the queued signal will include: 91.Bl -column ".Va si_value" 92.It Sy Member Ta Sy Value 93.It Va si_code Ta Dv SI_MESGQ 94.It Va si_value Ta 95the value stored in 96.Fa notification->sigev_value 97.It Va si_mqd Ta Fa mqdes 98.El 99.Pp 100If 101.Fa notification 102is 103.Dv NULL 104and the process is currently registered for notification by the specified 105message queue, the existing registration will be removed. 106.Pp 107When the notification is sent to the registered process, its registration 108is removed. 109The message queue then is available for registration. 110.Pp 111If a process has registered for notification of message arrival at a 112message queue and some thread is blocked in 113.Fn mq_receive 114waiting to receive a message when a message arrives at the queue, the 115arriving message will satisfy the appropriate 116.Fn mq_receive . 117The resulting behavior is as if the message queue remains empty, and no 118notification will be sent. 119.Sh RETURN VALUES 120.Rv -std 121.Sh ERRORS 122The 123.Fn mq_notify 124system call 125will fail if: 126.Bl -tag -width Er 127.It Bq Er EBADF 128The 129.Fa mqdes 130argument is not a valid message queue descriptor. 131.It Bq Er EBUSY 132Process is already registered for notification by the message queue. 133.It Bq Er EINVAL 134The asynchronous notification method in 135.Fa notification->sigev_notify 136is invalid or not supported. 137.El 138.Sh SEE ALSO 139.Xr mq_open 2 , 140.Xr mq_send 2 , 141.Xr mq_timedsend 2 , 142.Xr sigevent 3 , 143.Xr siginfo 3 144.Sh STANDARDS 145The 146.Fn mq_notify 147system call conforms to 148.St -p1003.1-2004 . 149.Sh HISTORY 150Support for 151.Tn POSIX 152message queues first appeared in 153.Fx 7.0 . 154.Sh COPYRIGHT 155Portions of this text are reprinted and reproduced in electronic form 156from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 157Portable Operating System Interface (POSIX), The Open Group Base 158Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 159Electrical and Electronics Engineers, Inc and The Open Group. In the 160event of any discrepancy between this version and the original IEEE and 161The Open Group Standard, the original IEEE and The Open Group Standard is 162the referee document. The original Standard can be obtained online at 163http://www.opengroup.org/unix/online.html. 164