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

msgsnd.3p (6553B)

    

  1. '\" et
  2. .TH MSGSND "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. msgsnd
  12. \(em XSI message send operation
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/msg.h>
  17. .P
  18. int msgsnd(int \fImsqid\fP, const void *\fImsgp\fP, size_t \fImsgsz\fP, int \fImsgflg\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fImsgsnd\fR()
  23. function operates on XSI message queues (see the Base Definitions volume of POSIX.1\(hy2017,
  24. .IR "Section 3.226" ", " "Message Queue").
  25. It is unspecified whether this function interoperates with the
  26. realtime interprocess communication facilities defined in
  27. .IR "Section 2.8" ", " "Realtime".
  28. .P
  29. The
  30. \fImsgsnd\fR()
  31. function shall send a message to the queue associated with the
  32. message queue identifier specified by
  33. .IR msqid .
  34. .P
  35. The application shall ensure that the argument
  36. .IR msgp
  37. points to a user-defined buffer that contains first a field of type
  38. .BR long
  39. specifying the type of the message, and then a data portion that holds
  40. the data bytes of the message. The structure below is an example of
  41. what this user-defined buffer might look like:
  42. .sp
  43. .RS 4
  44. .nf
  46. struct mymsg {
  47.     long   mtype;       /* Message type. */
  48.     char   mtext[1];    /* Message text. */
  49. }
  50. .fi
  51. .P
  52. .RE
  53. .P
  54. The structure member
  55. .IR mtype
  56. is a non-zero positive type
  57. .BR long
  58. that can be used by the receiving process for message selection.
  59. .P
  60. The structure member
  61. .IR mtext
  62. is any text of length
  63. .IR msgsz
  64. bytes. The argument
  65. .IR msgsz
  66. can range from 0 to a system-imposed maximum.
  67. .P
  68. The argument
  69. .IR msgflg
  70. specifies the action to be taken if one or more of the following is
  71. true:
  72. .IP " *" 4
  73. The number of bytes already on the queue is equal to
  74. .BR msg_qbytes ;
  75. see
  76. .IR <sys/msg.h> .
  77. .IP " *" 4
  78. The total number of messages on all queues system-wide is equal to the
  79. system-imposed limit.
  80. .P
  81. These actions are as follows:
  82. .IP " *" 4
  83. If (\fImsgflg\fP & IPC_NOWAIT)
  84. is non-zero, the message shall not be sent and the calling thread
  85. shall return immediately.
  86. .IP " *" 4
  87. If (\fImsgflg\fP & IPC_NOWAIT) is 0, the calling thread shall suspend
  88. execution until one of the following occurs:
  89. .RS 4 
  90. .IP -- 4
  91. The condition responsible for the suspension no longer exists, in which
  92. case the message is sent.
  93. .IP -- 4
  94. The message queue identifier
  95. .IR msqid
  96. is removed from the system; when this occurs,
  97. .IR errno
  98. shall be set to
  99. .BR [EIDRM] 
  100. and \-1 shall be returned.
  101. .IP -- 4
  102. The calling thread receives a signal that is to be caught; in this case
  103. the message is not sent and the calling thread resumes execution in the
  104. manner prescribed in
  105. .IR "\fIsigaction\fR\^(\|)".
  106. .RE
  107. .br
  108. .P
  109. Upon successful completion, the following actions are taken with
  110. respect to the data structure associated with
  111. .IR msqid ;
  112. see
  113. .IR <sys/msg.h> :
  114. .IP " *" 4
  115. .BR msg_qnum
  116. shall be incremented by 1.
  117. .IP " *" 4
  118. .BR msg_lspid
  119. shall be set to the process ID of the calling process.
  120. .IP " *" 4
  121. .BR msg_stime
  122. shall be set to the current time, as described in
  123. .IR "Section 2.7.1" ", " "IPC General Description".
  124. .SH "RETURN VALUE"
  125. Upon successful completion,
  126. \fImsgsnd\fR()
  127. shall return 0; otherwise, no message shall be sent,
  128. \fImsgsnd\fR()
  129. shall return \-1, and
  130. .IR errno
  131. shall be set to indicate the error.
  132. .SH ERRORS
  133. The
  134. \fImsgsnd\fR()
  135. function shall fail if:
  136. .TP
  137. .BR EACCES
  138. Operation permission is denied to the calling process; see
  139. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  140. .TP
  141. .BR EAGAIN
  142. The message cannot be sent for one of the reasons cited above and
  143. (\fImsgflg\fP & IPC_NOWAIT) is non-zero.
  144. .TP
  145. .BR EIDRM
  146. The message queue identifier
  147. .IR msqid
  148. is removed from the system.
  149. .TP
  150. .BR EINTR
  151. The
  152. \fImsgsnd\fR()
  153. function was interrupted by a signal.
  154. .TP
  155. .BR EINVAL
  156. The value of
  157. .IR msqid
  158. is not a valid message queue identifier, or the value of
  159. .IR mtype
  160. is less than 1; or the value of
  161. .IR msgsz
  162. is greater than the system-imposed limit.
  163. .LP
  164. .IR "The following sections are informative."
  165. .SH EXAMPLES
  166. .SS "Sending a Message"
  167. .P
  168. The following example sends a message to the queue identified by the
  169. .IR msqid
  170. argument (assuming that value has previously been set). This call
  171. specifies that an error should be reported if no message is available.
  172. The message size is calculated directly using the
  173. .IR sizeof
  174. operator.
  175. .sp
  176. .RS 4
  177. .nf
  179. #include <sys/msg.h>
  180. \&...
  181. int result;
  182. int msqid;
  183. struct message {
  184.     long type;
  185.     char text[20];
  186. } msg;
  187. .P
  188. msg.type = 1;
  189. strcpy(msg.text, "This is message 1");
  190. \&...
  191. result = msgsnd(msqid, (void *) &msg, sizeof(msg.text), IPC_NOWAIT);
  192. .fi
  193. .P
  194. .RE
  195. .SH "APPLICATION USAGE"
  196. The POSIX Realtime Extension defines alternative interfaces for interprocess communication
  197. (IPC). Application developers who need to use IPC should design their
  198. applications so that modules using the IPC routines described in
  199. .IR "Section 2.7" ", " "XSI Interprocess Communication"
  200. can be easily modified to use the alternative interfaces.
  201. .SH RATIONALE
  202. None.
  203. .SH "FUTURE DIRECTIONS"
  204. None.
  205. .SH "SEE ALSO"
  206. .IR "Section 2.7" ", " "XSI Interprocess Communication",
  207. .IR "Section 2.8" ", " "Realtime",
  208. .IR "\fImq_close\fR\^(\|)",
  209. .IR "\fImq_getattr\fR\^(\|)",
  210. .IR "\fImq_notify\fR\^(\|)",
  211. .IR "\fImq_open\fR\^(\|)",
  212. .IR "\fImq_receive\fR\^(\|)",
  213. .IR "\fImq_send\fR\^(\|)",
  214. .IR "\fImq_setattr\fR\^(\|)",
  215. .IR "\fImq_unlink\fR\^(\|)",
  216. .IR "\fImsgctl\fR\^(\|)",
  217. .IR "\fImsgget\fR\^(\|)",
  218. .IR "\fImsgrcv\fR\^(\|)",
  219. .IR "\fIsigaction\fR\^(\|)"
  220. .P
  221. The Base Definitions volume of POSIX.1\(hy2017,
  222. .IR "Section 3.226" ", " "Message Queue",
  223. .IR "\fB<sys_msg.h>\fP"
  224. .\"
  225. .SH COPYRIGHT
  226. Portions of this text are reprinted and reproduced in electronic form
  227. from IEEE Std 1003.1-2017, Standard for Information Technology
  228. -- Portable Operating System Interface (POSIX), The Open Group Base
  229. Specifications Issue 7, 2018 Edition,
  230. Copyright (C) 2018 by the Institute of
  231. Electrical and Electronics Engineers, Inc and The Open Group.
  232. In the event of any discrepancy between this version and the original IEEE and
  233. The Open Group Standard, the original IEEE and The Open Group Standard
  234. is the referee document. The original Standard can be obtained online at
  235. http://www.opengroup.org/unix/online.html .
  236. .PP
  237. Any typographical or formatting errors that appear
  238. in this page are most likely
  239. to have been introduced during the conversion of the source files to
  240. man page format. To report such errors, see
  241. https://www.kernel.org/doc/man-pages/reporting_bugs.html .