1.\" Copyright (c) 2005 David Xu <[email protected]> 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.\" $FreeBSD$ 39.\" 40.Dd July 15, 2016 41.Dt MQ_NOTIFY 2 42.Os 43.Sh NAME 44.Nm mq_notify 45.Nd "notify process that a message is available (REALTIME)" 46.Sh LIBRARY 47.Lb librt 48.Sh SYNOPSIS 49.In mqueue.h 50.Ft int 51.Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification" 52.Sh DESCRIPTION 53If the argument notification is not 54.Dv NULL , 55this system call will register the calling process to be notified of message 56arrival at an empty message queue associated with the specified message 57queue descriptor, 58.Fa mqdes . 59The notification specified by the 60.Fa notification 61argument will be sent to 62the process when the message queue transitions from empty to non-empty. 63At any time, only one process may be registered for notification by a 64message queue. 65If the calling process or any other process has already 66registered for notification of message arrival at the specified message 67queue, subsequent attempts to register for that message queue will fail. 68.Pp 69The 70.Fa notification 71argument points to a 72.Vt sigevent 73structure that defines how the calling process will be notified. 74If 75.Fa notification->sigev_notify 76is 77.Dv SIGEV_NONE , 78then no signal will be posted, but the error status and the return status 79for the operation will be set appropriately. 80For 81.Dv SIGEV_SIGNO 82and 83.Dv SIGEV_THREAD_ID 84notifications, 85the signal specified in 86.Fa notification->sigev_signo 87will be sent to the calling process 88.Pq Dv SIGEV_SIGNO 89or to the thread whose LWP ID is 90.Fa notification->sigev_notify_thread_id 91.Pq Dv SIGEV_THREAD_ID . 92The information for the queued signal will include: 93.Bl -column ".Va si_value" 94.It Sy Member Ta Sy Value 95.It Va si_code Ta Dv SI_MESGQ 96.It Va si_value Ta 97the value stored in 98.Fa notification->sigev_value 99.It Va si_mqd Ta Fa mqdes 100.El 101.Pp 102If 103.Fa notification 104is 105.Dv NULL 106and the process is currently registered for notification by the specified 107message queue, the existing registration will be removed. 108.Pp 109When the notification is sent to the registered process, its registration 110is removed. 111The message queue then is available for registration. 112.Pp 113If a process has registered for notification of message arrival at a 114message queue and some thread is blocked in 115.Fn mq_receive 116waiting to receive a message when a message arrives at the queue, the 117arriving message will satisfy the appropriate 118.Fn mq_receive . 119The resulting behavior is as if the message queue remains empty, and no 120notification will be sent. 121.Sh RETURN VALUES 122.Rv -std 123.Sh ERRORS 124The 125.Fn mq_notify 126system call 127will fail if: 128.Bl -tag -width Er 129.It Bq Er EBADF 130The 131.Fa mqdes 132argument is not a valid message queue descriptor. 133.It Bq Er EBUSY 134Process is already registered for notification by the message queue. 135.It Bq Er EINVAL 136The asynchronous notification method in 137.Fa notification->sigev_notify 138is invalid or not supported. 139.El 140.Sh SEE ALSO 141.Xr mq_open 2 , 142.Xr mq_send 2 , 143.Xr mq_timedsend 2 , 144.Xr sigevent 3 , 145.Xr siginfo 3 146.Sh STANDARDS 147The 148.Fn mq_notify 149system call conforms to 150.St -p1003.1-2004 . 151.Sh HISTORY 152Support for 153.Tn POSIX 154message queues first appeared in 155.Fx 7.0 . 156.Sh COPYRIGHT 157Portions of this text are reprinted and reproduced in electronic form 158from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 159Portable Operating System Interface (POSIX), The Open Group Base 160Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 161Electrical and Electronics Engineers, Inc and The Open Group. In the 162event of any discrepancy between this version and the original IEEE and 163The Open Group Standard, the original IEEE and The Open Group Standard is 164the referee document. The original Standard can be obtained online at 165http://www.opengroup.org/unix/online.html. 166