ipcs.1p (17805B)
- '\" et
- .TH IPCS "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- ipcs
- \(em report XSI interprocess communication facilities status
- .SH SYNOPSIS
- .LP
- .nf
- ipcs \fB[\fR-qms\fB] [\fR-a|-bcopt\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR ipcs
- utility shall write information about active interprocess communication
- facilities.
- .P
- Without options, information shall be written in short format for
- message queues, shared memory segments, and semaphore sets that are
- currently active in the system. Otherwise, the information that is
- displayed is controlled by the options specified.
- .SH OPTIONS
- The
- .IR ipcs
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The
- .IR ipcs
- utility accepts the following options:
- .IP "\fB\-q\fP" 10
- Write information about active message queues.
- .IP "\fB\-m\fP" 10
- Write information about active shared memory segments.
- .IP "\fB\-s\fP" 10
- Write information about active semaphore sets.
- .P
- If
- .BR \-q ,
- .BR \-m ,
- or
- .BR \-s
- are specified, only information about those facilities shall be
- written. If none of these three are specified, information about all
- three shall be written subject to the following options:
- .IP "\fB\-a\fP" 10
- Use all print options. (This is a shorthand notation for
- .BR \-b ,
- .BR \-c ,
- .BR \-o ,
- .BR \-p ,
- and
- .BR \-t .)
- .IP "\fB\-b\fP" 10
- Write information on maximum allowable size. (Maximum number of bytes
- in messages on queue for message queues, size of segments for shared
- memory, and number of semaphores in each set for semaphores.)
- .IP "\fB\-c\fP" 10
- Write creator's user name and group name; see below.
- .IP "\fB\-o\fP" 10
- Write information on outstanding usage. (Number of messages on queue
- and total number of bytes in messages on queue for message queues, and
- number of processes attached to shared memory segments.)
- .IP "\fB\-p\fP" 10
- Write process number information. (Process ID of the last process to
- send a message and process ID of the last process to receive a message
- on message queues, process ID of the creating process, and process ID
- of the last process to attach or detach on shared memory segments.)
- .IP "\fB\-t\fP" 10
- Write time information. (Time of the last control operation that
- changed the access permissions for all facilities, time of the last
- \fImsgsnd\fR()
- and
- \fImsgrcv\fR()
- operations on message queues, time of the last
- \fIshmat\fR()
- and
- \fIshmdt\fR()
- operations on shared memory, and time of the last
- \fIsemop\fR()
- operation on semaphores.)
- .SH OPERANDS
- None.
- .SH STDIN
- Not used.
- .SH "INPUT FILES"
- .IP " *" 4
- The group database
- .IP " *" 4
- The user database
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR ipcs :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fITZ\fP" 10
- Determine the timezone for the date and time strings written by
- .IR ipcs .
- If
- .IR TZ
- is unset or null, an unspecified default timezone shall be used.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- An introductory line shall be written with the format:
- .sp
- .RS 4
- .nf
- "IPC status from %s as of %s\en", <\fIsource\fP>, <\fIdate\fP>
- .fi
- .P
- .RE
- .P
- where <\fIsource\fP> indicates the source used to gather the statistics
- and <\fIdate\fP> is the information that would be produced by the
- .IR date
- command when invoked in the POSIX locale.
- .P
- The
- .IR ipcs
- utility then shall create up to three reports depending upon the
- .BR \-q ,
- .BR \-m ,
- and
- .BR \-s
- options. The first report shall indicate the status of message queues,
- the second report shall indicate the status of shared memory segments,
- and the third report shall indicate the status of semaphore sets.
- .P
- If the corresponding facility is not installed or has not been used
- since the last reboot, then the report shall be written out in the
- format:
- .sp
- .RS 4
- .nf
- "%s facility not in system.\en", <\fIfacility\fP>
- .fi
- .P
- .RE
- .P
- where <\fIfacility\fP> is
- .IR "Message Queue" ,
- .IR "Shared Memory" ,
- or
- .IR "Semaphore" ,
- as appropriate. If the facility has been installed and has been used
- since the last reboot, column headings separated by one or more
- <space>
- characters and followed by a
- <newline>
- shall be written as indicated below followed by the facility name
- written out using the format:
- .sp
- .RS 4
- .nf
- "%s:\en", <\fIfacility\fP>
- .fi
- .P
- .RE
- .P
- where <\fIfacility\fP> is
- .IR "Message Queues" ,
- .IR "Shared Memory" ,
- or
- .IR "Semaphores" ,
- as appropriate. On the second and third reports the column headings
- need not be written if the last column headings written already provide
- column headings for all information in that report.
- .P
- The column headings provided in the first column below and the meaning
- of the information in those columns shall be given in order below; the
- letters in parentheses indicate the options that shall cause the
- corresponding column to appear; ``all'' means that the column shall
- always appear. Each column is separated by one or more
- <space>
- characters. Note that these options only determine what information is
- provided for each report; they do not determine which reports are written.
- .IP "T (all)" 12
- Type of facility:
- .RS 12
- .IP "\fRq\fP" 8
- Message queue.
- .IP "\fRm\fP" 8
- Shared memory segment.
- .IP "\fRs\fP" 8
- Semaphore.
- .P
- This field is a single character written using the format
- .BR %c .
- .RE
- .IP "ID (all)" 12
- The identifier for the facility entry. This field shall be written
- using the format
- .BR %d .
- .IP "KEY (all)" 12
- The key used as an argument to
- \fImsgget\fR(),
- \fIsemget\fR(),
- or
- \fIshmget\fR()
- to create the facility entry.
- .RS 12
- .TP 10
- .BR Note:
- The key of a shared memory segment is changed to IPC_PRIVATE when the
- segment has been removed until all processes attached to the segment
- detach it.
- .P
- This field shall be written using the format \fR0x%x\fR.
- .RE
- .IP "MODE (all)" 12
- The facility access modes and flags. The mode shall consist of 11
- characters that are interpreted as follows.
- .RS 12
- .P
- The first character shall be:
- .IP "\fRS\fP" 8
- If a process is waiting on a
- \fImsgsnd\fR()
- operation.
- .IP "\fR\-\fP" 8
- If the above is not true.
- .P
- The second character shall be:
- .IP "\fRR\fP" 8
- If a process is waiting on a
- \fImsgrcv\fR()
- operation.
- .IP "\fRC\fP\ or\ \fR\-\fP" 8
- If the associated shared memory segment is to be cleared when the first
- attach operation is executed.
- .IP "\fR\-\fP" 8
- If none of the above is true.
- .P
- The next nine characters shall be interpreted as three sets of three
- bits each. The first set refers to the owner's permissions; the next
- to permissions of others in the usergroup of the facility entry; and
- the last to all others. Within each set, the first character indicates
- permission to read, the second character indicates permission to write
- or alter the facility entry, and the last character is a
- <hyphen-minus>
- (\c
- .BR '\-' ).
- .P
- The permissions shall be indicated as follows:
- .IP "\fIr\fP" 8
- If read permission is granted.
- .IP "\fIw\fP" 8
- If write permission is granted.
- .IP "\fIa\fP" 8
- If alter permission is granted.
- .IP "\fR\-\fP" 8
- If the indicated permission is not granted.
- .P
- The first character following the permissions specifies if there is an
- alternate or additional access control method associated with the
- facility. If there is no alternate or additional access control method
- associated with the facility, a single
- <space>
- shall be written; otherwise, another printable character is
- written.
- .RE
- .IP "OWNER (all)" 12
- The user name of the owner of the facility entry. If the user name of
- the owner is found in the user database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the user ID of the owner shall be written using the format
- .BR %d .
- .IP "GROUP (all)" 12
- The group name of the owner of the facility entry. If the group name
- of the owner is found in the group database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the group ID of the owner shall be written using the format
- .BR %d .
- .P
- The following nine columns shall be only written out for message
- queues:
- .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
- The user name of the creator of the facility entry. If the user name
- of the creator is found in the user database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the user ID of the creator shall be written using the format
- .BR %d .
- .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
- The group name of the creator of the facility entry. If the group name
- of the creator is found in the group database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the group ID of the creator shall be written using the format
- .BR %d .
- .IP "CBYTES (\fBa\fP,\fBo\fP)" 12
- The number of bytes in messages currently outstanding on the associated
- message queue. This field shall be written using the format
- .BR %d .
- .IP "QNUM (\fBa\fP,\fBo\fP)" 12
- The number of messages currently outstanding on the associated message
- queue. This field shall be written using the format
- .BR %d .
- .IP "QBYTES (\fBa\fP,\fBb\fP)" 12
- The maximum number of bytes allowed in messages outstanding on the
- associated message queue. This field shall be written using the format
- .BR %d .
- .IP "LSPID (\fBa\fP,\fBp\fP)" 12
- The process ID of the last process to send a message to the associated
- queue. This field shall be written using the format:
- .RS 12
- .sp
- .RS 4
- .nf
- "%d", <\fIpid\fP>
- .fi
- .P
- .RE
- .P
- where <\fIpid\fP> is 0 if no message has been sent to the corresponding
- message queue; otherwise, <\fIpid\fP> shall be the process ID of the
- last process to send a message to the queue.
- .RE
- .IP "LRPID (\fBa\fP,\fBp\fP)" 12
- The process ID of the last process to receive a message from the
- associated queue. This field shall be written using the format:
- .RS 12
- .sp
- .RS 4
- .nf
- "%d", <\fIpid\fP>
- .fi
- .P
- .RE
- .P
- where <\fIpid\fP> is 0 if no message has been received from the
- corresponding message queue; otherwise, <\fIpid\fP> shall be the
- process ID of the last process to receive a message from the queue.
- .RE
- .IP "STIME (\fBa\fP,\fBt\fP)" 12
- The time the last message was sent to the associated queue.
- If a message has been sent to the corresponding message queue,
- the hour, minute, and second of the last time a message
- was sent to the queue shall be written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- Otherwise, the format
- .BR \(dq\ no-entry\(dq
- shall be written.
- .IP "RTIME (\fBa\fP,\fBt\fP)" 12
- The time the last message was received from the associated queue.
- If a message has been received from the corresponding message queue,
- the hour, minute, and second of the last time a message was received
- from the queue shall be written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- Otherwise, the format
- .BR \(dq\ no-entry\(dq
- shall be written.
- .P
- The following eight columns shall be only written out for shared memory
- segments.
- .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
- The user of the creator of the facility entry. If the user name of the
- creator is found in the user database, at least the first eight column
- positions of the name shall be written using the format
- .BR %s .
- Otherwise, the user ID of the creator shall be written using the format
- .BR %d .
- .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
- The group name of the creator of the facility entry. If the group name
- of the creator is found in the group database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the group ID of the creator shall be written using the format
- .BR %d .
- .IP "NATTCH (\fBa\fP,\fBo\fP)" 12
- The number of processes attached to the associated shared memory
- segment. This field shall be written using the format
- .BR %d .
- .IP "SEGSZ (\fBa\fP,\fBb\fP)" 12
- The size of the associated shared memory segment. This field shall be
- written using the format
- .BR %d .
- .IP "CPID (\fBa\fP,\fBp\fP)" 12
- The process ID of the creator of the shared memory entry. This field
- shall be written using the format
- .BR %d .
- .IP "LPID (\fBa\fP,\fBp\fP)" 12
- The process ID of the last process to attach or detach the shared
- memory segment. This field shall be written using the format:
- .RS 12
- .sp
- .RS 4
- .nf
- "%d", <\fIpid\fP>
- .fi
- .P
- .RE
- .P
- where <\fIpid\fP> is 0 if no process has attached the corresponding
- shared memory segment; otherwise, <\fIpid\fP> shall be the process ID
- of the last process to attach or detach the segment.
- .RE
- .IP "ATIME (\fBa\fP,\fBt\fP)" 12
- The time the last attach on the associated shared memory segment was
- completed. If the corresponding shared memory segment has ever been
- attached, the hour, minute, and second of the last time the segment was
- attached shall be written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- Otherwise, the format
- .BR \(dq\ no-entry\(dq
- shall be written.
- .IP "DTIME (\fBa\fP,\fBt\fP)" 12
- The time the last detach on the associated shared memory segment was
- completed. If the corresponding shared memory segment has ever been
- detached, the hour, minute, and second of the last time the segment was
- detached shall be written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- Otherwise, the format
- .BR \(dq\ no-entry\(dq
- shall be written.
- .P
- The following four columns shall be only written out for semaphore
- sets:
- .IP "CREATOR (\fBa\fP,\fBc\fP)" 12
- The user of the creator of the facility entry. If the user name of the
- creator is found in the user database, at least the first eight column
- positions of the name shall be written using the format
- .BR %s .
- Otherwise, the user ID of the creator shall be written using the format
- .BR %d .
- .IP "CGROUP (\fBa\fP,\fBc\fP)" 12
- The group name of the creator of the facility entry. If the group name
- of the creator is found in the group database, at least the first eight
- column positions of the name shall be written using the format
- .BR %s .
- Otherwise, the group ID of the creator shall be written using the
- format
- .BR %d .
- .IP "NSEMS (\fBa\fP,\fBb\fP)" 12
- The number of semaphores in the set associated with the semaphore
- entry. This field shall be written using the format
- .BR %d .
- .IP "OTIME (\fBa\fP,\fBt\fP)" 12
- The time the last semaphore operation on the set associated with the
- semaphore entry was completed. If a semaphore operation has ever been
- performed on the corresponding semaphore set, the hour, minute, and
- second of the last semaphore operation on the semaphore set shall be
- written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- Otherwise, the format
- .BR \(dq\ no-entry\(dq
- shall be written.
- .P
- The following column shall be written for all three reports when it is
- requested:
- .IP "CTIME (\fBa\fP,\fBt\fP)" 12
- The time the associated entry was created or changed. The hour,
- minute, and second of the time when the associated entry was created
- shall be written using the format
- .BR %d :\c
- .BR %2.2d :\c
- .BR %2.2d .
- .SH STDERR
- The standard error shall be used only for diagnostic messages.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- Successful completion.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- Default.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- Things can change while
- .IR ipcs
- is running; the information it gives is guaranteed to be accurate
- only when it was retrieved.
- .SH EXAMPLES
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIipcrm\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .P
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "\fImsgrcv\fR\^(\|)",
- .IR "\fImsgsnd\fR\^(\|)",
- .IR "\fIsemget\fR\^(\|)",
- .IR "\fIsemop\fR\^(\|)",
- .IR "\fIshmat\fR\^(\|)",
- .IR "\fIshmdt\fR\^(\|)",
- .IR "\fIshmget\fR\^(\|)"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .