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_notify.3p (5641B)


  1. '\" et
  2. .TH MQ_NOTIFY "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_notify
  12. \(em notify process that a message is available
  13. (\fBREALTIME\fP)
  14. .SH SYNOPSIS
  15. .LP
  16. .nf
  17. #include <mqueue.h>
  18. .P
  19. int mq_notify(mqd_t \fImqdes\fP, const struct sigevent *\fInotification\fP);
  20. .fi
  21. .SH DESCRIPTION
  22. If the argument
  23. .IR notification
  24. is not NULL, this function shall register the calling process to be
  25. notified of message arrival at an empty message queue associated with
  26. the specified message queue descriptor,
  27. .IR mqdes .
  28. The notification specified by the
  29. .IR notification
  30. argument shall be sent to the process when the message queue transitions
  31. from empty to non-empty. At any time, only one process may be
  32. registered for notification by a message queue. If the calling process
  33. or any other process has already registered for notification of message
  34. arrival at the specified message queue, subsequent attempts to register
  35. for that message queue shall fail.
  36. .P
  37. If
  38. .IR notification
  39. is NULL and the process is currently registered for notification by the
  40. specified message queue, the existing registration shall be removed.
  41. .P
  42. When the notification is sent to the registered process, its
  43. registration shall be removed. The message queue shall then be available
  44. for registration.
  45. .P
  46. If a process has registered for notification of message arrival at a
  47. message queue and some thread is blocked in
  48. \fImq_receive\fR()
  49. or
  50. \fImq_timedreceive\fR()
  51. waiting to receive a message when a message arrives at the queue, the
  52. arriving message shall satisfy the appropriate
  53. \fImq_receive\fR()
  54. or
  55. \fImq_timedreceive\fR(),
  56. respectively. The resulting behavior is as if the message queue remains
  57. empty, and no notification shall be sent.
  58. .SH "RETURN VALUE"
  59. Upon successful completion, the
  60. \fImq_notify\fR()
  61. function shall return a value of zero; otherwise, the function shall
  62. return a value of \-1 and set
  63. .IR errno
  64. to indicate the error.
  65. .SH ERRORS
  66. The
  67. \fImq_notify\fR()
  68. function shall fail if:
  69. .TP
  70. .BR EBADF
  71. The
  72. .IR mqdes
  73. argument is not a valid message queue descriptor.
  74. .TP
  75. .BR EBUSY
  76. A process is already registered for notification by the message queue.
  77. .P
  78. The
  79. \fImq_notify\fR()
  80. function may fail if:
  81. .TP
  82. .BR EINVAL
  83. The
  84. .IR notification
  85. argument is NULL and the process is currently not registered.
  86. .LP
  87. .IR "The following sections are informative."
  88. .SH EXAMPLES
  89. The following program registers a notification request for the message
  90. queue named in its command-line argument. Notification is performed
  91. by creating a thread. The thread executes a function which reads one
  92. message from the queue and then terminates the process.
  93. .sp
  94. .RS 4
  95. .nf
  96. #include <pthread.h>
  97. #include <mqueue.h>
  98. #include <assert.h>
  99. #include <stdio.h>
  100. #include <stdlib.h>
  101. #include <unistd.h>
  102. .P
  103. static void /* Thread start function */
  104. tfunc(union sigval sv)
  105. {
  106. struct mq_attr attr;
  107. ssize_t nr;
  108. void *buf;
  109. mqd_t mqdes = *((mqd_t *) sv.sival_ptr);
  110. .P
  111. /* Determine maximum msg size; allocate buffer to receive msg */
  112. .P
  113. if (mq_getattr(mqdes, &attr) == -1) {
  114. perror("mq_getattr");
  115. exit(EXIT_FAILURE);
  116. }
  117. buf = malloc(attr.mq_msgsize);
  118. .P
  119. if (buf == NULL) {
  120. perror("malloc");
  121. exit(EXIT_FAILURE);
  122. }
  123. .P
  124. nr = mq_receive(mqdes, buf, attr.mq_msgsize, NULL);
  125. if (nr == -1) {
  126. perror("mq_receive");
  127. exit(EXIT_FAILURE);
  128. }
  129. .P
  130. printf("Read %ld bytes from message queue\en", (long) nr);
  131. free(buf);
  132. exit(EXIT_SUCCESS); /* Terminate the process */
  133. }
  134. .P
  135. int
  136. main(int argc, char *argv[])
  137. {
  138. mqd_t mqdes;
  139. struct sigevent not;
  140. .P
  141. assert(argc == 2);
  142. .P
  143. mqdes = mq_open(argv[1], O_RDONLY);
  144. if (mqdes == (mqd_t) -1) {
  145. perror("mq_open");
  146. exit(EXIT_FAILURE);
  147. }
  148. .P
  149. not.sigev_notify = SIGEV_THREAD;
  150. not.sigev_notify_function = tfunc;
  151. not.sigev_notify_attributes = NULL;
  152. not.sigev_value.sival_ptr = &mqdes; /* Arg. to thread func. */
  153. if (mq_notify(mqdes, &not) == -1) {
  154. perror("mq_notify");
  155. exit(EXIT_FAILURE);
  156. }
  157. .P
  158. pause(); /* Process will be terminated by thread function */
  159. }
  160. .fi
  161. .P
  162. .RE
  163. .SH "APPLICATION USAGE"
  164. None.
  165. .SH RATIONALE
  166. None.
  167. .SH "FUTURE DIRECTIONS"
  168. None.
  169. .SH "SEE ALSO"
  170. .IR "\fImq_open\fR\^(\|)",
  171. .IR "\fImq_send\fR\^(\|)",
  172. .IR "\fImq_receive\fR\^(\|)",
  173. .IR "\fImsgctl\fR\^(\|)",
  174. .IR "\fImsgget\fR\^(\|)",
  175. .IR "\fImsgrcv\fR\^(\|)",
  176. .IR "\fImsgsnd\fR\^(\|)"
  177. .P
  178. The Base Definitions volume of POSIX.1\(hy2017,
  179. .IR "\fB<mqueue.h>\fP"
  180. .\"
  181. .SH COPYRIGHT
  182. Portions of this text are reprinted and reproduced in electronic form
  183. from IEEE Std 1003.1-2017, Standard for Information Technology
  184. -- Portable Operating System Interface (POSIX), The Open Group Base
  185. Specifications Issue 7, 2018 Edition,
  186. Copyright (C) 2018 by the Institute of
  187. Electrical and Electronics Engineers, Inc and The Open Group.
  188. In the event of any discrepancy between this version and the original IEEE and
  189. The Open Group Standard, the original IEEE and The Open Group Standard
  190. is the referee document. The original Standard can be obtained online at
  191. http://www.opengroup.org/unix/online.html .
  192. .PP
  193. Any typographical or formatting errors that appear
  194. in this page are most likely
  195. to have been introduced during the conversion of the source files to
  196. man page format. To report such errors, see
  197. https://www.kernel.org/doc/man-pages/reporting_bugs.html .