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.\" $FreeBSD$ 39.\" 40.Dd November 29, 2005 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. 80If 81.Fa notification->sigev_notify 82is 83.Dv SIGEV_SIGNAL , 84then the signal specified in 85.Fa notification->sigev_signo 86will be sent to the process. 87The signal will be queued to the process and the value specified in 88.Fa notification->sigev_value 89will be the 90.Va si_value 91component of the generated signal. 92.Pp 93If 94.Fa notification 95is 96.Dv NULL 97and the process is currently registered for notification by the specified 98message queue, the existing registration will be removed. 99.Pp 100When the notification is sent to the registered process, its registration 101is removed. 102The message queue then is available for registration. 103.Pp 104If a process has registered for notification of message arrival at a 105message queue and some thread is blocked in 106.Fn mq_receive 107waiting to receive a message when a message arrives at the queue, the 108arriving message will satisfy the appropriate 109.Fn mq_receive . 110The resulting behavior is as if the message queue remains empty, and no 111notification will be sent. 112.Sh RETURN VALUES 113.Rv -std 114.Sh ERRORS 115The 116.Fn mq_notify 117system call 118will fail if: 119.Bl -tag -width Er 120.It Bq Er EBADF 121The 122.Fa mqdes 123argument is not a valid message queue descriptor. 124.It Bq Er EBUSY 125Process is already registered for notification by the message queue. 126.El 127.Sh SEE ALSO 128.Xr mq_open 2 , 129.Xr mq_send 2 , 130.Xr mq_timedsend 2 , 131.Xr siginfo 3 132.Sh STANDARDS 133The 134.Fn mq_notify 135system call conforms to 136.St -p1003.1-2004 . 137.Sh HISTORY 138Support for 139.Tn POSIX 140message queues first appeared in 141.Fx 7.0 . 142.Sh COPYRIGHT 143Portions of this text are reprinted and reproduced in electronic form 144from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- 145Portable Operating System Interface (POSIX), The Open Group Base 146Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of 147Electrical and Electronics Engineers, Inc and The Open Group. In the 148event of any discrepancy between this version and the original IEEE and 149The Open Group Standard, the original IEEE and The Open Group Standard is 150the referee document. The original Standard can be obtained online at 151http://www.opengroup.org/unix/online.html. 152