mqueues: Add librt (realtime library).
[dragonfly.git] / lib / librt / mq_notify.2
1 .\"     $NetBSD: mq_notify.3,v 1.1 2009/01/05 21:19:49 rmind Exp $
2 .\"
3 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
4 .\"
5 .Dd August 19, 2009
6 .Dt MQ_NOTIFY 2
7 .Os
8 .Sh NAME
9 .Nm mq_notify
10 .Nd notify process that a message is available (REALTIME)
11 .Sh LIBRARY
12 .Lb librt
13 .Sh SYNOPSIS
14 .In mqueue.h
15 .Ft int
16 .Fn mq_notify "mqd_t mqdes" "const struct sigevent *notification"
17 .Sh DESCRIPTION
18 If the argument
19 .Fa notification
20 is not
21 .Dv NULL ,
22 this function will register the calling process to be notified of
23 message arrival at an empty message queue associated with the
24 specified message queue descriptor,
25 .Fa mqdes .
26 The notification specified by the
27 .Fa notification
28 argument will be sent to the process when the message queue
29 transitions from empty to non-empty.
30 At any time, only one process may be registered for notification
31 by a message queue.
32 If the calling process or any other process has already registered
33 for notification of message arrival at the specified message queue,
34 subsequent attempts to register for that message queue fails.
35 .Pp
36 If
37 .Fa notification
38 is
39 .Dv NULL
40 and the process is currently registered for notification by the
41 specified message queue, the existing registration will be removed.
42 .Pp
43 When the notification is sent to the registered process,
44 its registration will be removed.
45 The message queue will then be available for registration.
46 .Pp
47 If a process has registered for notification of message arrival
48 at a message queue and some thread is blocked in
49 .Fn mq_receive
50 waiting to receive a message when a message arrives at the queue,
51 the arriving message will satisfy the appropriate
52 .Fn mq_receive .
53 The resulting behavior is as if the message queue remains empty,
54 and no notification will be sent.
55 .Sh RETURN VALUES
56 .Rv -std mq_notify
57 .Sh ERRORS
58 The
59 .Fn mq_notify
60 function fails if:
61 .Bl -tag -width Er
62 .It Bq Er EBADF
63 The
64 .Fa mqdes
65 argument is not a valid message queue descriptor.
66 .It Bq Er EBUSY
67 A process is already registered for notification by the message queue.
68 .El
69 .Sh SEE ALSO
70 .Xr mq_close 3 ,
71 .Xr mq_getattr 3 ,
72 .Xr mq_open 3 ,
73 .Xr mq_receive 3 ,
74 .Xr mq_send 3 ,
75 .Xr mq_setattr 3 ,
76 .Xr mq_unlink 3
77 .Sh STANDARDS
78 This function conforms to the
79 .St -p1003.1-2001
80 standard.
81 .Sh HISTORY
82 This function first appeared in
83 .Nx 5.0 .
84 .Sh COPYRIGHT
85 Portions of this text are reprinted and reproduced in electronic form
86 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
87 -- Portable Operating System Interface (POSIX), The Open Group Base
88 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
89 Electrical and Electronics Engineers, Inc and The Open Group.
90 In the
91 event of any discrepancy between this version and the original IEEE and
92 The Open Group Standard, the original IEEE and The Open Group Standard
93 is the referee document.
94 The original Standard can be obtained online at
95 http://www.opengroup.org/unix/online.html .