IPCS(1)                    POSIX Programmer's Manual                   IPCS(1)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       ipcs -- report XSI interprocess communication facilities status

SSYYNNOOPPSSIISS
       ipcs [[-qms]] [[-a|-bcopt]]

DDEESSCCRRIIPPTTIIOONN
       The _i_p_c_s utility shall write information about active interprocess
       communication facilities.

       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.

OOPPTTIIOONNSS
       The _i_p_c_s utility shall conform to the Base Definitions volume of
       POSIX.1-2017, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s.

       The _i_p_c_s utility accepts the following options:

       --qq        Write information about active message queues.

       --mm        Write information about active shared memory segments.

       --ss        Write information about active semaphore sets.

       If --qq, --mm, or --ss 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:

       --aa        Use all print options. (This is a shorthand notation for --bb,
                 --cc, --oo, --pp, and --tt.)

       --bb        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.)

       --cc        Write creator's user name and group name; see below.

       --oo        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.)

       --pp        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.)

       --tt        Write time information. (Time of the last control operation
                 that changed the access permissions for all facilities, time
                 of the last _m_s_g_s_n_d() and _m_s_g_r_c_v() operations on message
                 queues, time of the last _s_h_m_a_t() and _s_h_m_d_t() operations on
                 shared memory, and time of the last _s_e_m_o_p() operation on
                 semaphores.)

OOPPEERRAANNDDSS
       None.

SSTTDDIINN
       Not used.

IINNPPUUTT FFIILLEESS
        *  The group database

        *  The user database

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _i_p_c_s:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

       _L_C___A_L_L    If set to a non-empty string value, override the values of
                 all the other internationalization variables.

       _L_C___C_T_Y_P_E  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).

       _L_C___M_E_S_S_A_G_E_S
                 Determine the locale that should be used to affect the format
                 and contents of diagnostic messages written to standard
                 error.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

       _T_Z        Determine the timezone for the date and time strings written
                 by _i_p_c_s.  If _T_Z is unset or null, an unspecified default
                 timezone shall be used.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       Default.

SSTTDDOOUUTT
       An introductory line shall be written with the format:


           "IPC status from %s as of %s\n", <_s_o_u_r_c_e>, <_d_a_t_e>

       where <_s_o_u_r_c_e> indicates the source used to gather the statistics and
       <_d_a_t_e> is the information that would be produced by the _d_a_t_e command
       when invoked in the POSIX locale.

       The _i_p_c_s utility then shall create up to three reports depending upon
       the --qq, --mm, and --ss 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.

       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:


           "%s facility not in system.\n", <_f_a_c_i_l_i_t_y>

       where <_f_a_c_i_l_i_t_y> is _M_e_s_s_a_g_e _Q_u_e_u_e, _S_h_a_r_e_d _M_e_m_o_r_y, or _S_e_m_a_p_h_o_r_e, 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:


           "%s:\n", <_f_a_c_i_l_i_t_y>

       where <_f_a_c_i_l_i_t_y> is _M_e_s_s_a_g_e _Q_u_e_u_e_s, _S_h_a_r_e_d _M_e_m_o_r_y, or _S_e_m_a_p_h_o_r_e_s, 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.

       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.

       T (all)     Type of facility:

                   q       Message queue.

                   m       Shared memory segment.

                   s       Semaphore.

                   This field is a single character written using the format
                   %%cc.

       ID (all)    The identifier for the facility entry. This field shall be
                   written using the format %%dd.

       KEY (all)   The key used as an argument to _m_s_g_g_e_t(), _s_e_m_g_e_t(), or
                   _s_h_m_g_e_t() to create the facility entry.

                   NNoottee::     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.

                   This field shall be written using the format 0x%x.

       MODE (all)  The facility access modes and flags. The mode shall consist
                   of 11 characters that are interpreted as follows.

                   The first character shall be:

                   S       If a process is waiting on a _m_s_g_s_n_d() operation.

                   -       If the above is not true.

                   The second character shall be:

                   R       If a process is waiting on a _m_s_g_r_c_v() operation.

                   C or -  If the associated shared memory segment is to be
                           cleared when the first attach operation is
                           executed.

                   -       If none of the above is true.

                   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> (''--'').

                   The permissions shall be indicated as follows:

                   _r       If read permission is granted.

                   _w       If write permission is granted.

                   _a       If alter permission is granted.

                   -       If the indicated permission is not granted.

                   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.

       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 %%ss.  Otherwise, the user ID of the
                   owner shall be written using the format %%dd.

       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 %%ss.  Otherwise, the group ID of
                   the owner shall be written using the format %%dd.

       The following nine columns shall be only written out for message
       queues:

       CREATOR (aa,cc)
                   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 %%ss.  Otherwise, the user ID of the
                   creator shall be written using the format %%dd.

       CGROUP (aa,cc)
                   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 %%ss.  Otherwise, the group ID of
                   the creator shall be written using the format %%dd.

       CBYTES (aa,oo)
                   The number of bytes in messages currently outstanding on
                   the associated message queue. This field shall be written
                   using the format %%dd.

       QNUM (aa,oo)  The number of messages currently outstanding on the
                   associated message queue. This field shall be written using
                   the format %%dd.

       QBYTES (aa,bb)
                   The maximum number of bytes allowed in messages outstanding
                   on the associated message queue. This field shall be
                   written using the format %%dd.

       LSPID (aa,pp) The process ID of the last process to send a message to the
                   associated queue. This field shall be written using the
                   format:


                       "%d", <_p_i_d>

                   where <_p_i_d> is 0 if no message has been sent to the
                   corresponding message queue; otherwise, <_p_i_d> shall be the
                   process ID of the last process to send a message to the
                   queue.

       LRPID (aa,pp) The process ID of the last process to receive a message
                   from the associated queue. This field shall be written
                   using the format:


                       "%d", <_p_i_d>

                   where <_p_i_d> is 0 if no message has been received from the
                   corresponding message queue; otherwise, <_p_i_d> shall be the
                   process ID of the last process to receive a message from
                   the queue.

       STIME (aa,tt) 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 %%dd:%%22..22dd:%%22..22dd.  Otherwise, the format "" nnoo--eennttrryy""
                   shall be written.

       RTIME (aa,tt) 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 %%dd:%%22..22dd:%%22..22dd.
                   Otherwise, the format "" nnoo--eennttrryy"" shall be written.

       The following eight columns shall be only written out for shared memory
       segments.

       CREATOR (aa,cc)
                   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 %%ss.  Otherwise, the user ID of the
                   creator shall be written using the format %%dd.

       CGROUP (aa,cc)
                   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 %%ss.  Otherwise, the group ID of
                   the creator shall be written using the format %%dd.

       NATTCH (aa,oo)
                   The number of processes attached to the associated shared
                   memory segment. This field shall be written using the
                   format %%dd.

       SEGSZ (aa,bb) The size of the associated shared memory segment. This
                   field shall be written using the format %%dd.

       CPID (aa,pp)  The process ID of the creator of the shared memory entry.
                   This field shall be written using the format %%dd.

       LPID (aa,pp)  The process ID of the last process to attach or detach the
                   shared memory segment. This field shall be written using
                   the format:


                       "%d", <_p_i_d>

                   where <_p_i_d> is 0 if no process has attached the
                   corresponding shared memory segment; otherwise, <_p_i_d> shall
                   be the process ID of the last process to attach or detach
                   the segment.

       ATIME (aa,tt) 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 %%dd:%%22..22dd:%%22..22dd.  Otherwise, the
                   format "" nnoo--eennttrryy"" shall be written.

       DTIME (aa,tt) 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 %%dd:%%22..22dd:%%22..22dd.  Otherwise, the
                   format "" nnoo--eennttrryy"" shall be written.

       The following four columns shall be only written out for semaphore
       sets:

       CREATOR (aa,cc)
                   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 %%ss.  Otherwise, the user ID of the
                   creator shall be written using the format %%dd.

       CGROUP     (aa,cc)
                   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 %%ss.  Otherwise, the group ID of
                   the creator shall be written using the format %%dd.

       NSEMS (aa,bb) The number of semaphores in the set associated with the
                   semaphore entry. This field shall be written using the
                   format %%dd.

       OTIME (aa,tt) 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 %%dd:%%22..22dd:%%22..22dd.  Otherwise, the format
                   "" nnoo--eennttrryy"" shall be written.

       The following column shall be written for all three reports when it is
       requested:

       CTIME (aa,tt) 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
                   %%dd:%%22..22dd:%%22..22dd.

SSTTDDEERRRR
       The standard error shall be used only for diagnostic messages.

OOUUTTPPUUTT FFIILLEESS
       None.

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       Default.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Things can change while _i_p_c_s is running; the information it gives is
       guaranteed to be accurate only when it was retrieved.

EEXXAAMMPPLLEESS
       None.

RRAATTIIOONNAALLEE
       None.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _i_p_c_r_m

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s, _S_e_c_t_i_o_n _1_2_._2, _U_t_i_l_i_t_y _S_y_n_t_a_x _G_u_i_d_e_l_i_n_e_s

       The System Interfaces volume of POSIX.1-2017, _m_s_g_r_c_v(), _m_s_g_s_n_d(),
       _s_e_m_g_e_t(), _s_e_m_o_p(), _s_h_m_a_t(), _s_h_m_d_t(), _s_h_m_g_e_t()

CCOOPPYYRRIIGGHHTT
       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 .

       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 .



IEEE/The Open Group                  2017                              IPCS(1)
