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

msgctl.3p (5266B)


  1. '\" et
  2. .TH MSGCTL "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. msgctl
  12. \(em XSI message control operations
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/msg.h>
  17. .P
  18. int msgctl(int \fImsqid\fP, int \fIcmd\fP, struct msqid_ds *\fIbuf\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fImsgctl\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. \fImsgctl\fR()
  31. function shall provide message control operations as specified by
  32. .IR cmd .
  33. The following values for
  34. .IR cmd ,
  35. and the message control operations they specify, are:
  36. .IP IPC_STAT 12
  37. Place the current value of each member of the
  38. .BR msqid_ds
  39. data structure associated with
  40. .IR msqid
  41. into the structure pointed to by
  42. .IR buf .
  43. The contents of this structure are defined in
  44. .IR <sys/msg.h> .
  45. .IP IPC_SET 12
  46. Set the value of the following members of the
  47. .BR msqid_ds
  48. data structure associated with
  49. .IR msqid
  50. to the corresponding value found in the structure pointed to by
  51. .IR buf :
  52. .RS 12
  53. .sp
  54. .RS 4
  55. .nf
  56. msg_perm.uid
  57. msg_perm.gid
  58. msg_perm.mode
  59. msg_qbytes
  60. .fi
  61. .P
  62. .RE
  63. .P
  64. Also, the
  65. .IR msg_ctime
  66. timestamp shall be set to the current time, as described in
  67. .IR "Section 2.7.1" ", " "IPC General Description".
  68. .P
  69. IPC_SET can only be executed by a process with appropriate privileges
  70. or that has an effective user ID equal to the value of
  71. .BR msg_perm.cuid
  72. or
  73. .BR msg_perm.uid
  74. in the
  75. .BR msqid_ds
  76. data structure associated with
  77. .IR msqid .
  78. Only a process with appropriate privileges can raise the value of
  79. .BR msg_qbytes .
  80. .RE
  81. .IP IPC_RMID 12
  82. Remove the message queue identifier specified by
  83. .IR msqid
  84. from the system and destroy the message queue and
  85. .BR msqid_ds
  86. data structure associated with it. IPC_RMD can only be executed by a
  87. process with appropriate privileges or one that has an effective user
  88. ID equal to the value of
  89. .BR msg_perm.cuid
  90. or
  91. .BR msg_perm.uid
  92. in the
  93. .BR msqid_ds
  94. data structure associated with
  95. .IR msqid .
  96. .SH "RETURN VALUE"
  97. Upon successful completion,
  98. \fImsgctl\fR()
  99. shall return 0; otherwise, it shall return \-1 and set
  100. .IR errno
  101. to indicate the error.
  102. .SH ERRORS
  103. The
  104. \fImsgctl\fR()
  105. function shall fail if:
  106. .TP
  107. .BR EACCES
  108. The argument
  109. .IR cmd
  110. is IPC_STAT and the calling process does not have read permission; see
  111. .IR "Section 2.7" ", " "XSI Interprocess Communication".
  112. .TP
  113. .BR EINVAL
  114. The value of
  115. .IR msqid
  116. is not a valid message queue identifier; or the value of
  117. .IR cmd
  118. is not a valid command.
  119. .TP
  120. .BR EPERM
  121. The argument
  122. .IR cmd
  123. is IPC_RMID or IPC_SET
  124. and the effective user ID of the calling process is not equal to that
  125. of a process with appropriate privileges and it is not equal to the
  126. value of
  127. .BR msg_perm.cuid
  128. or
  129. .BR msg_perm.uid
  130. in the data structure associated with
  131. .IR msqid .
  132. .TP
  133. .BR EPERM
  134. The argument
  135. .IR cmd
  136. is IPC_SET, an attempt is being made to increase to the value of
  137. .BR msg_qbytes ,
  138. and the effective user ID of the calling process does not have
  139. appropriate privileges.
  140. .LP
  141. .IR "The following sections are informative."
  142. .SH EXAMPLES
  143. None.
  144. .SH "APPLICATION USAGE"
  145. The POSIX Realtime Extension defines alternative interfaces for interprocess communication
  146. (IPC). Application developers who need to use IPC should design their
  147. applications so that modules using the IPC routines described in
  148. .IR "Section 2.7" ", " "XSI Interprocess Communication"
  149. can be easily modified to use the alternative interfaces.
  150. .SH RATIONALE
  151. None.
  152. .SH "FUTURE DIRECTIONS"
  153. None.
  154. .SH "SEE ALSO"
  155. .IR "Section 2.7" ", " "XSI Interprocess Communication",
  156. .IR "Section 2.8" ", " "Realtime",
  157. .IR "\fImq_close\fR\^(\|)",
  158. .IR "\fImq_getattr\fR\^(\|)",
  159. .IR "\fImq_notify\fR\^(\|)",
  160. .IR "\fImq_open\fR\^(\|)",
  161. .IR "\fImq_receive\fR\^(\|)",
  162. .IR "\fImq_send\fR\^(\|)",
  163. .IR "\fImq_setattr\fR\^(\|)",
  164. .IR "\fImq_unlink\fR\^(\|)",
  165. .IR "\fImsgget\fR\^(\|)",
  166. .IR "\fImsgrcv\fR\^(\|)",
  167. .IR "\fImsgsnd\fR\^(\|)"
  168. .P
  169. The Base Definitions volume of POSIX.1\(hy2017,
  170. .IR "Section 3.226" ", " "Message Queue",
  171. .IR "\fB<sys_msg.h>\fP"
  172. .\"
  173. .SH COPYRIGHT
  174. Portions of this text are reprinted and reproduced in electronic form
  175. from IEEE Std 1003.1-2017, Standard for Information Technology
  176. -- Portable Operating System Interface (POSIX), The Open Group Base
  177. Specifications Issue 7, 2018 Edition,
  178. Copyright (C) 2018 by the Institute of
  179. Electrical and Electronics Engineers, Inc and The Open Group.
  180. In the event of any discrepancy between this version and the original IEEE and
  181. The Open Group Standard, the original IEEE and The Open Group Standard
  182. is the referee document. The original Standard can be obtained online at
  183. http://www.opengroup.org/unix/online.html .
  184. .PP
  185. Any typographical or formatting errors that appear
  186. in this page are most likely
  187. to have been introduced during the conversion of the source files to
  188. man page format. To report such errors, see
  189. https://www.kernel.org/doc/man-pages/reporting_bugs.html .