man-pages/man1p/ipcs.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "IPCS" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ipcs 
.SH NAME
ipcs \- report XSI interprocess communication facilities status
.SH SYNOPSIS
.LP
\fBipcs\fP \fB[\fP\fB-qms\fP\fB][\fP\fB-a | -bcopt\fP\fB]\fP\fB\fP
.SH DESCRIPTION
.LP
The \fIipcs\fP utility shall write information about active interprocess
communication facilities.
.LP
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
.LP
The \fIipcs\fP facility supports the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Section 12.2, Utility Syntax Guidelines.
.LP
The \fIipcs\fP utility accepts the following options:
.TP 7
\fB-q\fP
Write information about active message queues.
.TP 7
\fB-m\fP
Write information about active shared memory segments.
.TP 7
\fB-s\fP
Write information about active semaphore sets.
.sp
.LP
If \fB-q\fP, \fB-m\fP, or \fB-s\fP 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:
.TP 7
\fB-a\fP
Use all print options. (This is a shorthand notation for \fB-b\fP,
\fB-c\fP, \fB-o\fP, \fB-p\fP, and \fB-t\fP.)
.TP 7
\fB-b\fP
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.)
.TP 7
\fB-c\fP
Write creator's user name and group name; see below.
.TP 7
\fB-o\fP
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.)
.TP 7
\fB-p\fP
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.)
.TP 7
\fB-t\fP
Write time information. (Time of the last control operation that changed
the access permissions for all facilities, time of the
last \fImsgsnd\fP() and \fImsgrcv\fP() operations
on message queues, time of the last \fIshmat\fP() and \fIshmdt\fP()
operations on shared memory, and time of the last \fIsemop\fP() operation
on semaphores.)
.sp
.SH OPERANDS
.LP
None.
.SH STDIN
.LP
Not used.
.SH INPUT FILES
.IP " *" 3
The group database
.LP
.IP " *" 3
The user database
.LP
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIipcs\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_CTYPE\fP
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).
.TP 7
\fILC_MESSAGES\fP
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard
error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP
.TP 7
\fITZ\fP
Determine the timezone for the date and time strings written by \fIipcs\fP.
If \fITZ\fP is unset or null, an unspecified
default timezone shall be used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
An introductory line shall be written with the format:
.sp
.RS
.nf

\fB"IPC status from %s as of %s\\n", <\fP\fIsource\fP\fB>, <\fP\fIdate\fP\fB>
\fP
.fi
.RE
.LP
where <\fIsource\fP> indicates the source used to gather the statistics
and <\fIdate\fP> is the information that
would be produced by the \fIdate\fP command when invoked in the POSIX
locale.
.LP
The \fIipcs\fP utility then shall create up to three reports depending
upon the \fB-q\fP, \fB-m\fP, and \fB-s\fP 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.
.LP
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
.nf

\fB"%s facility not in system.\\n", <\fP\fIfacility\fP\fB>
\fP
.fi
.RE
.LP
where <\fIfacility\fP> is \fIMessage Queue\fP, \fIShared Memory\fP,
or \fISemaphore\fP, as appropriate. If the
facility has been installed and has been used since the last reboot,
column headings separated by one or more spaces and followed
by a <newline> shall be written as indicated below followed by the
facility name written out using the format:
.sp
.RS
.nf

\fB"%s:\\n", <\fP\fIfacility\fP\fB>
\fP
.fi
.RE
.LP
where <\fIfacility\fP> is \fIMessage Queues\fP, \fIShared Memory\fP,
or \fISemaphores\fP, 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.
.LP
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>s. Note that these options only determine
what information is provided for each report; they do not determine
which reports are written.
.TP 7
T (all)
Type of facility: 
.TP 7
\fBq\fP
.RS
Message queue.
.RE
.TP 7
\fBm\fP
.RS
Shared memory segment.
.RE
.TP 7
\fBs\fP
.RS
Semaphore.
.RE
.sp
.LP
This field is a single character written using the format \fB%c\fP
\&.
.TP 7
ID (all)
The identifier for the facility entry. This field shall be written
using the format \fB%d\fP .
.TP 7
KEY (all)
The key used as an argument to \fImsgget\fP(), \fIsemget\fP(), or
\fIshmget\fP() to create the facility
entry.  
.TP 7
\fBNote:\fP
.RS
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.
.RE
.sp
This field shall be written using the format \fB0x%x\fP.
.TP 7
MODE (all)
The facility access modes and flags. The mode shall consist of 11
characters that are interpreted as follows. 
.LP
The first character shall be:
.TP 7
\fBS\fP
.RS
If a process is waiting on a \fImsgsnd\fP() operation.
.RE
.TP 7
\fB-\fP
.RS
If the above is not true.
.RE
.sp
.LP
The second character shall be:
.TP 7
\fBR\fP
.RS
If a process is waiting on a \fImsgrcv\fP() operation.
.RE
.TP 7
\fBC\fP\ or\ \fB-\fP
.RS
If the associated shared memory segment is to be cleared when the
first attach operation is executed.
.RE
.TP 7
\fB-\fP
.RS
If none of the above is true.
.RE
.sp
.LP
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 minus sign ( \fB'-'\fP ).
.LP
The permissions shall be indicated as follows:
.TP 7
\fIr\fP
.RS
If read permission is granted.
.RE
.TP 7
\fIw\fP
.RS
If write permission is granted.
.RE
.TP 7
\fIa\fP
.RS
If alter permission is granted.
.RE
.TP 7
\fB-\fP
.RS
If the indicated permission is not granted.
.RE
.sp
.LP
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.
.TP 7
OWNER (all)
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 \fB%s\fP . Otherwise, the user ID of the owner shall
be written using the format \fB%d\fP .
.TP 7
GROUP (all)
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 \fB%s\fP . Otherwise, the group ID of the owner shall
be written using the format \fB%d\fP .
.sp
.LP
The following nine columns shall be only written out for message queues:
.TP 7
CREATOR (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the user ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
CGROUP (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the group ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
CBYTES (\fBa\fP,\fBo\fP)
The number of bytes in messages currently outstanding on the associated
message queue. This field shall be written using the
format \fB%d\fP .
.TP 7
QNUM (\fBa\fP,\fBo\fP)
The number of messages currently outstanding on the associated message
queue. This field shall be written using the format
\fB%d\fP .
.TP 7
QBYTES (\fBa\fP,\fBb\fP)
The maximum number of bytes allowed in messages outstanding on the
associated message queue. This field shall be written using
the format \fB%d\fP .
.TP 7
LSPID (\fBa\fP,\fBp\fP)
The process ID of the last process to send a message to the associated
queue. This field shall be written using the format: 
.sp
.RS
.nf

\fB"%d", <\fP\fIpid\fP\fB>
\fP
.fi
.RE
.LP
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.
.TP 7
LRPID (\fBa\fP,\fBp\fP)
The process ID of the last process to receive a message from the associated
queue. This field shall be written using the
format: 
.sp
.RS
.nf

\fB"%d", <\fP\fIpid\fP\fB>
\fP
.fi
.RE
.LP
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.
.TP 7
STIME (\fBa\fP,\fBt\fP)
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 \fB%d\fP :
\fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP
shall be written.
.TP 7
RTIME (\fBa\fP,\fBt\fP)
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
\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP
shall be written.
.sp
.LP
The following eight columns shall be only written out for shared memory
segments.
.TP 7
CREATOR (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the user ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
CGROUP (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the group ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
NATTCH (\fBa\fP,\fBo\fP)
The number of processes attached to the associated shared memory segment.
This field shall be written using the format
\fB%d\fP .
.TP 7
SEGSZ (\fBa\fP,\fBb\fP)
The size of the associated shared memory segment. This field shall
be written using the format \fB%d\fP .
.TP 7
CPID (\fBa\fP,\fBp\fP)
The process ID of the creator of the shared memory entry. This field
shall be written using the format \fB%d\fP .
.TP 7
LPID (\fBa\fP,\fBp\fP)
The process ID of the last process to attach or detach the shared
memory segment. This field shall be written using the format:
.sp
.RS
.nf

\fB"%d", <\fP\fIpid\fP\fB>
\fP
.fi
.RE
.LP
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.
.TP 7
ATIME (\fBa\fP,\fBt\fP)
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
\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP
shall be written.
.TP 7
DTIME (\fBa\fP,\fBt\fP)
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
\fB%d\fP : \fB%2.2d\fP : \fB%2.2d\fP . Otherwise, the format \fB"\ no-entry"\fP
shall be written.
.sp
.LP
The following four columns shall be only written out for semaphore
sets:
.TP 7
CREATOR (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the user ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
CGROUP (\fBa\fP,\fBc\fP)
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 \fB%s\fP . Otherwise, the group ID of the creator
shall be written using the format \fB%d\fP .
.TP 7
NSEMS (\fBa\fP,\fBb\fP)
The number of semaphores in the set associated with the semaphore
entry. This field shall be written using the format
\fB%d\fP .
.TP 7
OTIME (\fBa\fP,\fBt\fP)
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 \fB%d\fP : \fB%2.2d\fP
: \fB%2.2d\fP . Otherwise, the format
\fB"\ no-entry"\fP shall be written.
.sp
.LP
The following column shall be written for all three reports when it
is requested:
.TP 7
CTIME (\fBa\fP,\fBt\fP)
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 \fB%d\fP : \fB%2.2d\fP :
\fB%2.2d\fP .
.sp
.SH STDERR
.LP
The standard error shall be used only for diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
Successful completion.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Things can change while \fIipcs\fP is running; the information it
gives is guaranteed to be accurate only when it was
retrieved.
.SH EXAMPLES
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fImsgrcv\fP(),
\fImsgsnd\fP(), \fIsemget\fP(), \fIsemop\fP(), \fIshmat\fP(), \fIshmdt\fP(),
\fIshmget\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .