Annotation of src/lib/librt/mq_receive.3, Revision 1.6
1.6 ! wiz 1: .\" $NetBSD: mq_receive.3,v 1.5 2015/11/18 13:19:52 pgoyette Exp $
1.1 rmind 2: .\"
3: .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
4: .\"
1.6 ! wiz 5: .Dd November 18, 2015
1.1 rmind 6: .Dt MQ_RECEIVE 3
7: .Os
8: .Sh NAME
9: .Nm mq_receive, mq_timedreceive
10: .Nd receive a message from a message queue (REALTIME)
11: .Sh LIBRARY
12: .Lb librt
13: .Sh SYNOPSIS
14: .In mqueue.h
15: .Ft ssize_t
16: .Fo mq_receive
17: .Fa "mqd_t mqdes"
18: .Fa "char *msg_ptr"
19: .Fa "size_t msg_len"
20: .Fa "unsigned *msg_prio"
21: .Fc
22: .In mqueue.h
23: .In time.h
24: .Ft ssize_t
25: .Fo mq_timedreceive
26: .Fa "mqd_t mqdes"
27: .Fa "char *restrict msg_ptr"
28: .Fa "size_t msg_len"
29: .Fa "unsigned *restrict msg_prio"
30: .Fa "const struct timespec *restrict abs_timeout"
31: .Fc
32: .Sh DESCRIPTION
33: The
34: .Fn mq_receive
35: function receives the oldest of the highest priority message(s)
36: from the message queue specified by
37: .Fa mqdes .
38: If the size of the buffer in bytes, specified by the
39: .Fa msg_len
40: argument, is less than the
41: .Va mq_msgsize
42: attribute of the message queue, the function fails and returns an error.
43: Otherwise, the selected message will be removed from the queue and copied
44: to the buffer pointed to by the
45: .Fa msg_ptr
46: argument.
47: .Pp
48: If the argument
49: .Fa msg_prio
50: is not
51: .Dv NULL ,
52: the priority of the selected message will be stored in the location
53: referenced by
54: .Fa msg_prio .
55: .Pp
56: If the specified message queue is empty and
57: .Dv O_NONBLOCK
58: is not set in the message queue description associated with
59: .Fa mqdes ,
60: .Fn mq_receive
61: blocks until a message is enqueued on the message queue or until
62: .Fn mq_receive
63: is interrupted by a signal.
64: If more than one thread is waiting to receive a message when a
65: message arrives at an empty queue, then the thread of highest
66: priority that has been waiting the longest will be selected to
67: receive the message.
68: If the specified message queue is empty and
69: .Dv O_NONBLOCK
70: is set in the message queue description associated with
71: .Fa mqdes ,
72: no message will be removed from the queue, and
73: .Fn mq_receive
74: returns an error.
75: .Pp
76: The timeout expires when the absolute time specified by
77: .Fa abs_timeout
78: passes, as measured by the clock on which timeouts are based (that is,
79: when the value of that clock equals or exceeds
80: .Fa abs_timeout ) ,
81: or if the absolute time specified by
82: .Fa abs_timeout
83: has already been passed at the time of the call.
84: .Pp
85: The resolution of the timeout is based on the CLOCK_REALTIME clock.
86: The
87: .Fa timespec
88: argument is defined in the
1.2 joerg 89: .In time.h
1.1 rmind 90: header.
91: .Pp
92: Under no circumstance will the operation fail with a timeout if a
93: message can be removed from the message queue immediately.
94: The validity of the
95: .Fa abs_timeout
96: parameter will not be checked if a message can be removed from the
97: message queue immediately.
98: .Sh RETURN VALUES
99: Upon successful completion, the
100: .Fn mq_receive
101: and
102: .Fn mq_timedreceive
1.5 pgoyette 103: functions return the length of the selected message in bytes, and the
104: message is removed from the queue.
1.1 rmind 105: Otherwise, no message will be removed from the queue,
106: the functions return a value of
107: \-1, and set the global variable
108: .Va errno
109: to indicate the error.
110: .Sh ERRORS
111: The
112: .Fn mq_receive
113: and
114: .Fn mq_timedreceive
115: functions fail if:
116: .Bl -tag -width Er
117: .It Bq Er EAGAIN
118: .Dv O_NONBLOCK
119: was set in the message description associated with
120: .Fa mqdes ,
121: and the specified message queue is empty.
122: .It Bq Er EBADF
123: The
124: .Fa mqdes
125: argument is not a valid message queue descriptor open for reading.
126: .It Bq Er EINTR
127: The
128: .Fn mq_receive
129: or
130: .Fn mq_timedreceive
131: operation was interrupted by a signal.
132: .It Bq Er EINVAL
133: The process or thread would have blocked, and the
134: .Fa abs_timeout
135: parameter specified a nanoseconds field value less than zero
136: or greater than or equal to 1000 million.
137: .It Bq Er EMSGSIZE
138: The specified message buffer size,
139: .Fa msg_len ,
140: is less than the message size attribute of the message queue.
141: .It Bq Er ETIMEDOUT
142: The
143: .Dv O_NONBLOCK
144: flag was not set when the message queue was opened,
145: but no message arrived on the queue before the specified timeout expired.
146: .El
147: .Sh SEE ALSO
1.3 jruoho 148: .Xr mq 3 ,
149: .Xr mq_send 3
1.1 rmind 150: .Sh STANDARDS
151: These functions are expected to conform to the
152: .St -p1003.1-2001
153: standard.
154: .Sh HISTORY
155: The
156: .Fn mq_receive
157: and
158: .Fn mq_timedreceive
159: functions first appeared in
160: .Nx 5.0 .
161: .Sh COPYRIGHT
162: Portions of this text are reprinted and reproduced in electronic form
163: from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
164: -- Portable Operating System Interface (POSIX), The Open Group Base
165: Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
166: Electrical and Electronics Engineers, Inc and The Open Group.
167: In the
168: event of any discrepancy between this version and the original IEEE and
169: The Open Group Standard, the original IEEE and The Open Group Standard
170: is the referee document.
171: The original Standard can be obtained online at
1.4 njoly 172: .Lk http://www.opengroup.org/unix/online.html .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to mq_receive.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / librt