logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

mq_open.3p (8916B)


  1. '\" et
  2. .TH MQ_OPEN "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. mq_open
  12. \(em open a message queue
  13. (\fBREALTIME\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <mqueue.h>
  18. .P
  19. mqd_t mq_open(const char *\fIname\fP, int \fIoflag\fP, ...);
  20. .fi
  21. .SH DESCRIPTION
  22. The
  23. \fImq_open\fR()
  24. function shall establish the connection between a process and a message
  25. queue with a message queue descriptor. It shall create an open message
  26. queue description that refers to the message queue, and a message queue
  27. descriptor that refers to that open message queue description. The
  28. message queue descriptor is used by other functions to refer to that
  29. message queue. The
  30. .IR name
  31. argument points to a string naming a message queue. It is unspecified
  32. whether the name appears in the file system and is visible to other
  33. functions that take pathnames as arguments. The
  34. .IR name
  35. argument conforms to the construction rules for a pathname, except that
  36. the interpretation of
  37. <slash>
  38. characters other than the leading
  39. <slash>
  40. character in
  41. .IR name
  42. is implementation-defined, and that the length limits for the
  43. .IR name
  44. argument are implementation-defined and need not be the same as the
  45. pathname limits
  46. {PATH_MAX}
  47. and
  48. {NAME_MAX}.
  49. If
  50. .IR name
  51. begins with the
  52. <slash>
  53. character, then processes calling
  54. \fImq_open\fR()
  55. with the same value of
  56. .IR name
  57. shall refer to the same message queue object, as long as that name
  58. has not been removed. If
  59. .IR name
  60. does not begin with the
  61. <slash>
  62. character, the effect is implementation-defined. If the
  63. .IR name
  64. argument is not the name of an existing message queue and creation is
  65. not requested,
  66. \fImq_open\fR()
  67. shall fail and return an error.
  68. .P
  69. A message queue descriptor may be implemented using a file
  70. descriptor, in which case applications can open up to at least
  71. {OPEN_MAX}
  72. file and message queues.
  73. .P
  74. The
  75. .IR oflag
  76. argument requests the desired receive and/or send access to the message
  77. queue. The requested access permission to receive messages or send
  78. messages shall be granted if the calling process would be granted read
  79. or write access, respectively, to an equivalently protected file.
  80. .P
  81. The value of
  82. .IR oflag
  83. is the bitwise-inclusive OR of values from the following list.
  84. Applications shall specify exactly one of the first three values
  85. (access modes) below in the value of
  86. .IR oflag :
  87. .IP O_RDONLY 12
  88. Open the message queue for receiving messages. The process can use the
  89. returned message queue descriptor with
  90. \fImq_receive\fR(),
  91. but not
  92. \fImq_send\fR().
  93. A message queue may be open multiple times in the same or different
  94. processes for receiving messages.
  95. .IP O_WRONLY 12
  96. Open the queue for sending messages. The process can use the returned
  97. message queue descriptor with
  98. \fImq_send\fR()
  99. but not
  100. \fImq_receive\fR().
  101. A message queue may be open multiple times in the same or different
  102. processes for sending messages.
  103. .IP O_RDWR 12
  104. Open the queue for both receiving and sending messages. The process
  105. can use any of the functions allowed for O_RDONLY and O_WRONLY. A
  106. message queue may be open multiple times in the same or different
  107. processes for sending messages.
  108. .P
  109. Any combination of the remaining flags may be specified in the value of
  110. .IR oflag :
  111. .IP O_CREAT 12
  112. Create a message queue. It requires two additional arguments:
  113. .IR mode ,
  114. which shall be of type
  115. .BR mode_t ,
  116. and
  117. .IR attr ,
  118. which shall be a pointer to an
  119. .BR mq_attr
  120. structure. If the pathname
  121. .IR name
  122. has already been used to create a message queue that still exists, then
  123. this flag shall have no effect, except as noted under O_EXCL.
  124. Otherwise, a message queue shall be created without any messages in
  125. it. The user ID of the message queue shall be set to the effective
  126. user ID of the process. The group ID of the message queue shall be
  127. set to the effective group ID of the process; however, if the
  128. .IR name
  129. argument is visible in the file system, the group ID may be set
  130. to the group ID of the containing directory. When bits in
  131. .IR mode
  132. other than the file permission bits are specified, the effect is
  133. unspecified. If
  134. .IR attr
  135. is NULL, the message queue shall be created with implementation-defined
  136. default message queue attributes. If
  137. .IR attr
  138. is non-NULL and the calling process has appropriate privileges on
  139. .IR name ,
  140. the message queue
  141. .IR mq_maxmsg
  142. and
  143. .IR mq_msgsize
  144. attributes shall be set to the values of the corresponding members in the
  145. .BR mq_attr
  146. structure referred to by
  147. .IR attr .
  148. The values of the
  149. .IR mq_flags
  150. and
  151. .IR mq_curmsgs
  152. members of the
  153. .BR mq_attr
  154. structure shall be ignored. If
  155. .IR attr
  156. is non-NULL, but the calling process does not have appropriate
  157. privileges on
  158. .IR name ,
  159. the
  160. \fImq_open\fR()
  161. function shall fail and return an error without creating the message
  162. queue.
  163. .IP O_EXCL 12
  164. If O_EXCL and O_CREAT are set,
  165. \fImq_open\fR()
  166. shall fail if the message queue
  167. .IR name
  168. exists. The check for the existence of the message queue and the
  169. creation of the message queue if it does not exist shall be atomic with
  170. respect to other threads executing
  171. \fImq_open\fR()
  172. naming the same
  173. .IR name
  174. with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set,
  175. the result is undefined.
  176. .IP O_NONBLOCK 12
  177. Determines whether an
  178. \fImq_send\fR()
  179. or
  180. \fImq_receive\fR()
  181. waits for resources or messages that are not currently available, or
  182. fails with
  183. .IR errno
  184. set to
  185. .BR [EAGAIN] ;
  186. see
  187. .IR "\fImq_send\fR\^(\|)"
  188. and
  189. .IR "\fImq_receive\fR\^(\|)"
  190. for details.
  191. .P
  192. The
  193. \fImq_open\fR()
  194. function does not add or remove messages from the queue.
  195. .SH "RETURN VALUE"
  196. Upon successful completion, the function shall return a message queue
  197. descriptor; otherwise, the function shall return (\fBmqd_t\fP)\-1
  198. and set
  199. .IR errno
  200. to indicate the error.
  201. .SH ERRORS
  202. The
  203. \fImq_open\fR()
  204. function shall fail if:
  205. .TP
  206. .BR EACCES
  207. The message queue exists and the permissions specified by
  208. .IR oflag
  209. are denied, or the message queue does not exist and permission to
  210. create the message queue is denied.
  211. .TP
  212. .BR EEXIST
  213. O_CREAT and O_EXCL are set and the named message queue already exists.
  214. .TP
  215. .BR EINTR
  216. The
  217. \fImq_open\fR()
  218. function was interrupted by a signal.
  219. .TP
  220. .BR EINVAL
  221. The
  222. \fImq_open\fR()
  223. function is not supported for the given name.
  224. .TP
  225. .BR EINVAL
  226. O_CREAT was specified in
  227. .IR oflag ,
  228. the value of
  229. .IR attr
  230. is not NULL, and either
  231. .IR mq_maxmsg
  232. or
  233. .IR mq_msgsize
  234. was less than or equal to zero.
  235. .TP
  236. .BR EMFILE
  237. Too many message queue descriptors or file descriptors are currently in
  238. use by this process.
  239. .TP
  240. .BR ENFILE
  241. Too many message queues are currently open in the system.
  242. .TP
  243. .BR ENOENT
  244. O_CREAT is not set and the named message queue does not exist.
  245. .TP
  246. .BR ENOSPC
  247. There is insufficient space for the creation of the new message queue.
  248. .br
  249. .P
  250. If any of the following conditions occur, the
  251. \fImq_open\fR()
  252. function may return (\c
  253. .BR mqd_t )\-1
  254. and set
  255. .IR errno
  256. to the corresponding value.
  257. .TP
  258. .BR ENAMETOOLONG
  259. .br
  260. The length of the
  261. .IR name
  262. argument exceeds
  263. {_POSIX_PATH_MAX}
  264. on systems that do not support the XSI option
  265. or exceeds
  266. {_XOPEN_PATH_MAX}
  267. on XSI systems,
  268. or has a pathname component that is longer than
  269. {_POSIX_NAME_MAX}
  270. on systems that do not support the XSI option
  271. or longer than
  272. {_XOPEN_NAME_MAX}
  273. on XSI systems.
  274. .LP
  275. .IR "The following sections are informative."
  276. .SH EXAMPLES
  277. None.
  278. .SH "APPLICATION USAGE"
  279. None.
  280. .SH RATIONALE
  281. None.
  282. .SH "FUTURE DIRECTIONS"
  283. A future version might require the
  284. \fImq_open\fR()
  285. and
  286. \fImq_unlink\fR()
  287. functions to have semantics similar to normal file system operations.
  288. .SH "SEE ALSO"
  289. .IR "\fImq_close\fR\^(\|)",
  290. .IR "\fImq_getattr\fR\^(\|)",
  291. .IR "\fImq_receive\fR\^(\|)",
  292. .IR "\fImq_send\fR\^(\|)",
  293. .IR "\fImq_setattr\fR\^(\|)",
  294. .IR "\fImq_unlink\fR\^(\|)",
  295. .IR "\fImsgctl\fR\^(\|)",
  296. .IR "\fImsgget\fR\^(\|)",
  297. .IR "\fImsgrcv\fR\^(\|)",
  298. .IR "\fImsgsnd\fR\^(\|)"
  299. .P
  300. The Base Definitions volume of POSIX.1\(hy2017,
  301. .IR "\fB<mqueue.h>\fP"
  302. .\"
  303. .SH COPYRIGHT
  304. Portions of this text are reprinted and reproduced in electronic form
  305. from IEEE Std 1003.1-2017, Standard for Information Technology
  306. -- Portable Operating System Interface (POSIX), The Open Group Base
  307. Specifications Issue 7, 2018 Edition,
  308. Copyright (C) 2018 by the Institute of
  309. Electrical and Electronics Engineers, Inc and The Open Group.
  310. In the event of any discrepancy between this version and the original IEEE and
  311. The Open Group Standard, the original IEEE and The Open Group Standard
  312. is the referee document. The original Standard can be obtained online at
  313. http://www.opengroup.org/unix/online.html .
  314. .PP
  315. Any typographical or formatting errors that appear
  316. in this page are most likely
  317. to have been introduced during the conversion of the source files to
  318. man page format. To report such errors, see
  319. https://www.kernel.org/doc/man-pages/reporting_bugs.html .