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

ipcs.1p (17805B)


  1. '\" et
  2. .TH IPCS "1P" 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. ipcs
  12. \(em report XSI interprocess communication facilities status
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. ipcs \fB[\fR-qms\fB] [\fR-a|-bcopt\fB]\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR ipcs
  21. utility shall write information about active interprocess communication
  22. facilities.
  23. .P
  24. Without options, information shall be written in short format for
  25. message queues, shared memory segments, and semaphore sets that are
  26. currently active in the system. Otherwise, the information that is
  27. displayed is controlled by the options specified.
  28. .SH OPTIONS
  29. The
  30. .IR ipcs
  31. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  32. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  33. .P
  34. The
  35. .IR ipcs
  36. utility accepts the following options:
  37. .IP "\fB\-q\fP" 10
  38. Write information about active message queues.
  39. .IP "\fB\-m\fP" 10
  40. Write information about active shared memory segments.
  41. .IP "\fB\-s\fP" 10
  42. Write information about active semaphore sets.
  43. .P
  44. If
  45. .BR \-q ,
  46. .BR \-m ,
  47. or
  48. .BR \-s
  49. are specified, only information about those facilities shall be
  50. written. If none of these three are specified, information about all
  51. three shall be written subject to the following options:
  52. .IP "\fB\-a\fP" 10
  53. Use all print options. (This is a shorthand notation for
  54. .BR \-b ,
  55. .BR \-c ,
  56. .BR \-o ,
  57. .BR \-p ,
  58. and
  59. .BR \-t .)
  60. .IP "\fB\-b\fP" 10
  61. Write information on maximum allowable size. (Maximum number of bytes
  62. in messages on queue for message queues, size of segments for shared
  63. memory, and number of semaphores in each set for semaphores.)
  64. .IP "\fB\-c\fP" 10
  65. Write creator's user name and group name; see below.
  66. .IP "\fB\-o\fP" 10
  67. Write information on outstanding usage. (Number of messages on queue
  68. and total number of bytes in messages on queue for message queues, and
  69. number of processes attached to shared memory segments.)
  70. .IP "\fB\-p\fP" 10
  71. Write process number information. (Process ID of the last process to
  72. send a message and process ID of the last process to receive a message
  73. on message queues, process ID of the creating process, and process ID
  74. of the last process to attach or detach on shared memory segments.)
  75. .IP "\fB\-t\fP" 10
  76. Write time information. (Time of the last control operation that
  77. changed the access permissions for all facilities, time of the last
  78. \fImsgsnd\fR()
  79. and
  80. \fImsgrcv\fR()
  81. operations on message queues, time of the last
  82. \fIshmat\fR()
  83. and
  84. \fIshmdt\fR()
  85. operations on shared memory, and time of the last
  86. \fIsemop\fR()
  87. operation on semaphores.)
  88. .SH OPERANDS
  89. None.
  90. .SH STDIN
  91. Not used.
  92. .SH "INPUT FILES"
  93. .IP " *" 4
  94. The group database
  95. .IP " *" 4
  96. The user database
  97. .SH "ENVIRONMENT VARIABLES"
  98. The following environment variables shall affect the execution of
  99. .IR ipcs :
  100. .IP "\fILANG\fP" 10
  101. Provide a default value for the internationalization variables that are
  102. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  103. .IR "Section 8.2" ", " "Internationalization Variables"
  104. for the precedence of internationalization variables used to determine
  105. the values of locale categories.)
  106. .IP "\fILC_ALL\fP" 10
  107. If set to a non-empty string value, override the values of all the
  108. other internationalization variables.
  109. .IP "\fILC_CTYPE\fP" 10
  110. Determine the locale for the interpretation of sequences of bytes of
  111. text data as characters (for example, single-byte as opposed to
  112. multi-byte characters in arguments).
  113. .IP "\fILC_MESSAGES\fP" 10
  114. .br
  115. Determine the locale that should be used to affect the format and
  116. contents of diagnostic messages written to standard error.
  117. .IP "\fINLSPATH\fP" 10
  118. Determine the location of message catalogs for the processing of
  119. .IR LC_MESSAGES .
  120. .IP "\fITZ\fP" 10
  121. Determine the timezone for the date and time strings written by
  122. .IR ipcs .
  123. If
  124. .IR TZ
  125. is unset or null, an unspecified default timezone shall be used.
  126. .SH "ASYNCHRONOUS EVENTS"
  127. Default.
  128. .SH STDOUT
  129. An introductory line shall be written with the format:
  130. .sp
  131. .RS 4
  132. .nf
  133. "IPC status from %s as of %s\en", <\fIsource\fP>, <\fIdate\fP>
  134. .fi
  135. .P
  136. .RE
  137. .P
  138. where <\fIsource\fP> indicates the source used to gather the statistics
  139. and <\fIdate\fP> is the information that would be produced by the
  140. .IR date
  141. command when invoked in the POSIX locale.
  142. .P
  143. The
  144. .IR ipcs
  145. utility then shall create up to three reports depending upon the
  146. .BR \-q ,
  147. .BR \-m ,
  148. and
  149. .BR \-s
  150. options. The first report shall indicate the status of message queues,
  151. the second report shall indicate the status of shared memory segments,
  152. and the third report shall indicate the status of semaphore sets.
  153. .P
  154. If the corresponding facility is not installed or has not been used
  155. since the last reboot, then the report shall be written out in the
  156. format:
  157. .sp
  158. .RS 4
  159. .nf
  160. "%s facility not in system.\en", <\fIfacility\fP>
  161. .fi
  162. .P
  163. .RE
  164. .P
  165. where <\fIfacility\fP> is
  166. .IR "Message Queue" ,
  167. .IR "Shared Memory" ,
  168. or
  169. .IR "Semaphore" ,
  170. as appropriate. If the facility has been installed and has been used
  171. since the last reboot, column headings separated by one or more
  172. <space>
  173. characters and followed by a
  174. <newline>
  175. shall be written as indicated below followed by the facility name
  176. written out using the format:
  177. .sp
  178. .RS 4
  179. .nf
  180. "%s:\en", <\fIfacility\fP>
  181. .fi
  182. .P
  183. .RE
  184. .P
  185. where <\fIfacility\fP> is
  186. .IR "Message Queues" ,
  187. .IR "Shared Memory" ,
  188. or
  189. .IR "Semaphores" ,
  190. as appropriate. On the second and third reports the column headings
  191. need not be written if the last column headings written already provide
  192. column headings for all information in that report.
  193. .P
  194. The column headings provided in the first column below and the meaning
  195. of the information in those columns shall be given in order below; the
  196. letters in parentheses indicate the options that shall cause the
  197. corresponding column to appear; ``all'' means that the column shall
  198. always appear. Each column is separated by one or more
  199. <space>
  200. characters. Note that these options only determine what information is
  201. provided for each report; they do not determine which reports are written.
  202. .IP "T (all)" 12
  203. Type of facility:
  204. .RS 12
  205. .IP "\fRq\fP" 8
  206. Message queue.
  207. .IP "\fRm\fP" 8
  208. Shared memory segment.
  209. .IP "\fRs\fP" 8
  210. Semaphore.
  211. .P
  212. This field is a single character written using the format
  213. .BR %c .
  214. .RE
  215. .IP "ID (all)" 12
  216. The identifier for the facility entry. This field shall be written
  217. using the format
  218. .BR %d .
  219. .IP "KEY (all)" 12
  220. The key used as an argument to
  221. \fImsgget\fR(),
  222. \fIsemget\fR(),
  223. or
  224. \fIshmget\fR()
  225. to create the facility entry.
  226. .RS 12
  227. .TP 10
  228. .BR Note:
  229. The key of a shared memory segment is changed to IPC_PRIVATE when the
  230. segment has been removed until all processes attached to the segment
  231. detach it.
  232. .P
  233. This field shall be written using the format \fR0x%x\fR.
  234. .RE
  235. .IP "MODE (all)" 12
  236. The facility access modes and flags. The mode shall consist of 11
  237. characters that are interpreted as follows.
  238. .RS 12
  239. .P
  240. The first character shall be:
  241. .IP "\fRS\fP" 8
  242. If a process is waiting on a
  243. \fImsgsnd\fR()
  244. operation.
  245. .IP "\fR\-\fP" 8
  246. If the above is not true.
  247. .P
  248. The second character shall be:
  249. .IP "\fRR\fP" 8
  250. If a process is waiting on a
  251. \fImsgrcv\fR()
  252. operation.
  253. .IP "\fRC\fP\ or\ \fR\-\fP" 8
  254. If the associated shared memory segment is to be cleared when the first
  255. attach operation is executed.
  256. .IP "\fR\-\fP" 8
  257. If none of the above is true.
  258. .P
  259. The next nine characters shall be interpreted as three sets of three
  260. bits each. The first set refers to the owner's permissions; the next
  261. to permissions of others in the usergroup of the facility entry; and
  262. the last to all others. Within each set, the first character indicates
  263. permission to read, the second character indicates permission to write
  264. or alter the facility entry, and the last character is a
  265. <hyphen-minus>
  266. (\c
  267. .BR '\-' ).
  268. .P
  269. The permissions shall be indicated as follows:
  270. .IP "\fIr\fP" 8
  271. If read permission is granted.
  272. .IP "\fIw\fP" 8
  273. If write permission is granted.
  274. .IP "\fIa\fP" 8
  275. If alter permission is granted.
  276. .IP "\fR\-\fP" 8
  277. If the indicated permission is not granted.
  278. .P
  279. The first character following the permissions specifies if there is an
  280. alternate or additional access control method associated with the
  281. facility. If there is no alternate or additional access control method
  282. associated with the facility, a single
  283. <space>
  284. shall be written; otherwise, another printable character is
  285. written.
  286. .RE
  287. .IP "OWNER (all)" 12
  288. The user name of the owner of the facility entry. If the user name of
  289. the owner is found in the user database, at least the first eight
  290. column positions of the name shall be written using the format
  291. .BR %s .
  292. Otherwise, the user ID of the owner shall be written using the format
  293. .BR %d .
  294. .IP "GROUP (all)" 12
  295. The group name of the owner of the facility entry. If the group name
  296. of the owner is found in the group database, at least the first eight
  297. column positions of the name shall be written using the format
  298. .BR %s .
  299. Otherwise, the group ID of the owner shall be written using the format
  300. .BR %d .
  301. .P
  302. The following nine columns shall be only written out for message
  303. queues:
  304. .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
  305. The user name of the creator of the facility entry. If the user name
  306. of the creator is found in the user database, at least the first eight
  307. column positions of the name shall be written using the format
  308. .BR %s .
  309. Otherwise, the user ID of the creator shall be written using the format
  310. .BR %d .
  311. .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
  312. The group name of the creator of the facility entry. If the group name
  313. of the creator is found in the group database, at least the first eight
  314. column positions of the name shall be written using the format
  315. .BR %s .
  316. Otherwise, the group ID of the creator shall be written using the format
  317. .BR %d .
  318. .IP "CBYTES (\fBa\fP,\fBo\fP)" 12
  319. The number of bytes in messages currently outstanding on the associated
  320. message queue. This field shall be written using the format
  321. .BR %d .
  322. .IP "QNUM (\fBa\fP,\fBo\fP)" 12
  323. The number of messages currently outstanding on the associated message
  324. queue. This field shall be written using the format
  325. .BR %d .
  326. .IP "QBYTES (\fBa\fP,\fBb\fP)" 12
  327. The maximum number of bytes allowed in messages outstanding on the
  328. associated message queue. This field shall be written using the format
  329. .BR %d .
  330. .IP "LSPID (\fBa\fP,\fBp\fP)" 12
  331. The process ID of the last process to send a message to the associated
  332. queue. This field shall be written using the format:
  333. .RS 12
  334. .sp
  335. .RS 4
  336. .nf
  337. "%d", <\fIpid\fP>
  338. .fi
  339. .P
  340. .RE
  341. .P
  342. where <\fIpid\fP> is 0 if no message has been sent to the corresponding
  343. message queue; otherwise, <\fIpid\fP> shall be the process ID of the
  344. last process to send a message to the queue.
  345. .RE
  346. .IP "LRPID (\fBa\fP,\fBp\fP)" 12
  347. The process ID of the last process to receive a message from the
  348. associated queue. This field shall be written using the format:
  349. .RS 12
  350. .sp
  351. .RS 4
  352. .nf
  353. "%d", <\fIpid\fP>
  354. .fi
  355. .P
  356. .RE
  357. .P
  358. where <\fIpid\fP> is 0 if no message has been received from the
  359. corresponding message queue; otherwise, <\fIpid\fP> shall be the
  360. process ID of the last process to receive a message from the queue.
  361. .RE
  362. .IP "STIME (\fBa\fP,\fBt\fP)" 12
  363. The time the last message was sent to the associated queue.
  364. If a message has been sent to the corresponding message queue,
  365. the hour, minute, and second of the last time a message
  366. was sent to the queue shall be written using the format
  367. .BR %d :\c
  368. .BR %2.2d :\c
  369. .BR %2.2d .
  370. Otherwise, the format
  371. .BR \(dq\ no-entry\(dq
  372. shall be written.
  373. .IP "RTIME (\fBa\fP,\fBt\fP)" 12
  374. The time the last message was received from the associated queue.
  375. If a message has been received from the corresponding message queue,
  376. the hour, minute, and second of the last time a message was received
  377. from the queue shall be written using the format
  378. .BR %d :\c
  379. .BR %2.2d :\c
  380. .BR %2.2d .
  381. Otherwise, the format
  382. .BR \(dq\ no-entry\(dq
  383. shall be written.
  384. .P
  385. The following eight columns shall be only written out for shared memory
  386. segments.
  387. .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
  388. The user of the creator of the facility entry. If the user name of the
  389. creator is found in the user database, at least the first eight column
  390. positions of the name shall be written using the format
  391. .BR %s .
  392. Otherwise, the user ID of the creator shall be written using the format
  393. .BR %d .
  394. .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
  395. The group name of the creator of the facility entry. If the group name
  396. of the creator is found in the group database, at least the first eight
  397. column positions of the name shall be written using the format
  398. .BR %s .
  399. Otherwise, the group ID of the creator shall be written using the format
  400. .BR %d .
  401. .IP "NATTCH (\fBa\fP,\fBo\fP)" 12
  402. The number of processes attached to the associated shared memory
  403. segment. This field shall be written using the format
  404. .BR %d .
  405. .IP "SEGSZ (\fBa\fP,\fBb\fP)" 12
  406. The size of the associated shared memory segment. This field shall be
  407. written using the format
  408. .BR %d .
  409. .IP "CPID (\fBa\fP,\fBp\fP)" 12
  410. The process ID of the creator of the shared memory entry. This field
  411. shall be written using the format
  412. .BR %d .
  413. .IP "LPID (\fBa\fP,\fBp\fP)" 12
  414. The process ID of the last process to attach or detach the shared
  415. memory segment. This field shall be written using the format:
  416. .RS 12
  417. .sp
  418. .RS 4
  419. .nf
  420. "%d", <\fIpid\fP>
  421. .fi
  422. .P
  423. .RE
  424. .P
  425. where <\fIpid\fP> is 0 if no process has attached the corresponding
  426. shared memory segment; otherwise, <\fIpid\fP> shall be the process ID
  427. of the last process to attach or detach the segment.
  428. .RE
  429. .IP "ATIME (\fBa\fP,\fBt\fP)" 12
  430. The time the last attach on the associated shared memory segment was
  431. completed. If the corresponding shared memory segment has ever been
  432. attached, the hour, minute, and second of the last time the segment was
  433. attached shall be written using the format
  434. .BR %d :\c
  435. .BR %2.2d :\c
  436. .BR %2.2d .
  437. Otherwise, the format
  438. .BR \(dq\ no-entry\(dq
  439. shall be written.
  440. .IP "DTIME (\fBa\fP,\fBt\fP)" 12
  441. The time the last detach on the associated shared memory segment was
  442. completed. If the corresponding shared memory segment has ever been
  443. detached, the hour, minute, and second of the last time the segment was
  444. detached shall be written using the format
  445. .BR %d :\c
  446. .BR %2.2d :\c
  447. .BR %2.2d .
  448. Otherwise, the format
  449. .BR \(dq\ no-entry\(dq
  450. shall be written.
  451. .P
  452. The following four columns shall be only written out for semaphore
  453. sets:
  454. .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
  455. The user of the creator of the facility entry. If the user name of the
  456. creator is found in the user database, at least the first eight column
  457. positions of the name shall be written using the format
  458. .BR %s .
  459. Otherwise, the user ID of the creator shall be written using the format
  460. .BR %d .
  461. .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
  462. The group name of the creator of the facility entry. If the group name
  463. of the creator is found in the group database, at least the first eight
  464. column positions of the name shall be written using the format
  465. .BR %s .
  466. Otherwise, the group ID of the creator shall be written using the
  467. format
  468. .BR %d .
  469. .IP "NSEMS (\fBa\fP,\fBb\fP)" 12
  470. The number of semaphores in the set associated with the semaphore
  471. entry. This field shall be written using the format
  472. .BR %d .
  473. .IP "OTIME (\fBa\fP,\fBt\fP)" 12
  474. The time the last semaphore operation on the set associated with the
  475. semaphore entry was completed. If a semaphore operation has ever been
  476. performed on the corresponding semaphore set, the hour, minute, and
  477. second of the last semaphore operation on the semaphore set shall be
  478. written using the format
  479. .BR %d :\c
  480. .BR %2.2d :\c
  481. .BR %2.2d .
  482. Otherwise, the format
  483. .BR \(dq\ no-entry\(dq
  484. shall be written.
  485. .P
  486. The following column shall be written for all three reports when it is
  487. requested:
  488. .IP "CTIME (\fBa\fP,\fBt\fP)" 12
  489. The time the associated entry was created or changed. The hour,
  490. minute, and second of the time when the associated entry was created
  491. shall be written using the format
  492. .BR %d :\c
  493. .BR %2.2d :\c
  494. .BR %2.2d .
  495. .SH STDERR
  496. The standard error shall be used only for diagnostic messages.
  497. .SH "OUTPUT FILES"
  498. None.
  499. .SH "EXTENDED DESCRIPTION"
  500. None.
  501. .SH "EXIT STATUS"
  502. The following exit values shall be returned:
  503. .IP "\00" 6
  504. Successful completion.
  505. .IP >0 6
  506. An error occurred.
  507. .SH "CONSEQUENCES OF ERRORS"
  508. Default.
  509. .LP
  510. .IR "The following sections are informative."
  511. .SH "APPLICATION USAGE"
  512. Things can change while
  513. .IR ipcs
  514. is running; the information it gives is guaranteed to be accurate
  515. only when it was retrieved.
  516. .SH EXAMPLES
  517. None.
  518. .SH RATIONALE
  519. None.
  520. .SH "FUTURE DIRECTIONS"
  521. None.
  522. .SH "SEE ALSO"
  523. .IR "\fIipcrm\fR\^"
  524. .P
  525. The Base Definitions volume of POSIX.1\(hy2017,
  526. .IR "Chapter 8" ", " "Environment Variables",
  527. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  528. .P
  529. The System Interfaces volume of POSIX.1\(hy2017,
  530. .IR "\fImsgrcv\fR\^(\|)",
  531. .IR "\fImsgsnd\fR\^(\|)",
  532. .IR "\fIsemget\fR\^(\|)",
  533. .IR "\fIsemop\fR\^(\|)",
  534. .IR "\fIshmat\fR\^(\|)",
  535. .IR "\fIshmdt\fR\^(\|)",
  536. .IR "\fIshmget\fR\^(\|)"
  537. .\"
  538. .SH COPYRIGHT
  539. Portions of this text are reprinted and reproduced in electronic form
  540. from IEEE Std 1003.1-2017, Standard for Information Technology
  541. -- Portable Operating System Interface (POSIX), The Open Group Base
  542. Specifications Issue 7, 2018 Edition,
  543. Copyright (C) 2018 by the Institute of
  544. Electrical and Electronics Engineers, Inc and The Open Group.
  545. In the event of any discrepancy between this version and the original IEEE and
  546. The Open Group Standard, the original IEEE and The Open Group Standard
  547. is the referee document. The original Standard can be obtained online at
  548. http://www.opengroup.org/unix/online.html .
  549. .PP
  550. Any typographical or formatting errors that appear
  551. in this page are most likely
  552. to have been introduced during the conversion of the source files to
  553. man page format. To report such errors, see
  554. https://www.kernel.org/doc/man-pages/reporting_bugs.html .