rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 13:39:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

shell: Update commands to use descriptions.

Browse Source
This commit is contained in:
Chris Johns 2016-11-08 21:33:20 +11:00
parent 227aaea494
commit bf61a8b14e
7 changed files with 4101 additions and 4286 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

87
shell/configuration_and_init.rst
View File

@ -296,15 +296,17 @@ Functions
This section describes the Shell related C functions which are publicly This section describes the Shell related C functions which are publicly
available related to initialization and configuration. available related to initialization and configuration.
.. raw:: latex
\clearpage
rtems_shell_init - Initialize the shell rtems_shell_init - Initialize the shell
--------------------------------------- ---------------------------------------
.. index:: initialization .. index:: initialization
**CALLING SEQUENCE:**
.. index:: rtems_shell_init .. index:: rtems_shell_init
.. code-block:: c CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_shell_init( rtems_status_code rtems_shell_init(
const char *task_name, const char *task_name,
@ -316,71 +318,66 @@ rtems_shell_init - Initialize the shell
rtems_login_check login_check rtems_login_check login_check
); );
**DIRECTIVE STATUS CODES:** DIRECTIVE STATUS CODES:
``RTEMS_SUCCESSFUL`` - Shell task spawned successfully
*others* - to indicate a failure condition
``RTEMS_SUCCESSFUL`` - Shell task spawned successfully DESCRIPTION:
This service creates a task with the specified characteristics to run the RTEMS
Shell attached to the specified ``devname``.
others - to indicate a failure condition NOTES:
This method invokes the ``rtems_task_create`` and ``rtems_task_start``
directives and as such may return any status code that those directives may
return.
**DESCRIPTION:** There is one POSIX key necessary for all shell instances together and one
POSIX key value pair per instance. You should make sure that your RTEMS
configuration accounts for these resources.
This service creates a task with the specified characteristics to run the RTEMS .. raw:: latex
Shell attached to the specified ``devname``.
**NOTES:** \clearpage
This method invokes the ``rtems_task_create`` and ``rtems_task_start``
directives and as such may return any status code that those directives may
return.
There is one POSIX key necessary for all shell instances together and one POSIX
key value pair per instance. You should make sure that your RTEMS configuration
accounts for these resources.
rtems_shell_login_check - Default login check handler rtems_shell_login_check - Default login check handler
----------------------------------------------------- -----------------------------------------------------
.. index:: initialization .. index:: initialization
**CALLING SEQUENCE:**
.. index:: rtems_shell_login_check .. index:: rtems_shell_login_check
.. code:: c CALLING SEQUENCE:
.. code:: c
bool rtems_shell_login_check( bool rtems_shell_login_check(
const char *user, const char *user,
const char *passphrase const char *passphrase
); );
**DIRECTIVE STATUS CODES:** DIRECTIVE STATUS CODES:
``true`` - login is allowed, and
``false`` - otherwise.
``true`` - login is allowed, and DESCRIPTION:
``false`` - otherwise. This function checks if the specified passphrase is valid for the specified
user.
**DESCRIPTION:** NOTES:
As a side-effect if the specified passphrase is valid for the specified
user, this function:
This function checks if the specified passphrase is valid for the specified - performs a filesystem change root operation to the directory of the
user. specified user if the directory path is non-empty,
**NOTES:** - changes the owner of the current shell device to the UID of the specified
As a side-effect if the specified passphrase is valid for the specified user,
this function:
- performs a filesystem change root operation to the directory of the specified
user if the directory path is non-empty,
- changes the owner of the current shell device to the UID of the specified
user, user,
- sets the real and effective UID of the current user environment to the UID of - sets the real and effective UID of the current user environment to the
the specified user, UID of the specified user,
- sets the real and effective GID of the current user environment to the GID of - sets the real and effective GID of the current user environment to the
the specified user, and GID of the specified user, and
- sets the supplementary group IDs of the current user environment to the - sets the supplementary group IDs of the current user environment to the
supplementary group IDs of the specified user. supplementary group IDs of the specified user.
In case the filesystem change root operation fails, then the environment setup In case the filesystem change root operation fails, then the environment
is aborted and ``false`` is returned. setup is aborted and ``false`` is returned.

2543
shell/file_and_directory.rst
View File

File diff suppressed because it is too large Load Diff

1096
shell/general_commands.rst
View File

File diff suppressed because it is too large Load Diff

2
shell/index.rst
View File

@ -39,7 +39,7 @@ to the Community Project hosted at http://www.rtems.org/.
================ ============================= ================ =============================
.. toctree:: .. toctree::
:maxdepth: 3 :maxdepth: 4
:numbered: :numbered:
preface preface

526
shell/memory_commands.rst
View File

@ -34,46 +34,45 @@ subsection is dedicated to each of the commands and
describes the behavior and configuration of that describes the behavior and configuration of that
command as well as providing an example usage. command as well as providing an example usage.
.. raw:: latex
\clearpage
.. _mdump: .. _mdump:
mdump - display contents of memory mdump - display contents of memory
---------------------------------- ----------------------------------
.. index:: mdump .. index:: mdump
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
mdump [address [length [size]]] mdump [address [length [size]]]
**DESCRIPTION:** DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` in ``size`` byte units specified on the command line.
This command displays the contents of memory at the ``address`` and ``length`` When ``size`` is not provided, it defaults to ``1`` byte units. Values of
in ``size`` byte units specified on the command line. ``1``, ``2``, and ``4`` are valid; all others will cause an error to be
reported.
When ``size`` is not provided, it defaults to ``1`` byte units. Values of When ``length`` is not provided, it defaults to ``320`` which is twenty
``1``, ``2``, and ``4`` are valid; all others will cause an error to be lines of output with sixteen bytes of output per line.
reported.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``address`` is not provided, it defaults to ``0x00000000``.
of output with sixteen bytes of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. EXIT STATUS:
This command always returns 0 to indicate success.
**EXIT STATUS:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
This command always returns 0 to indicate success. EXAMPLES:
The following is an example of how to use ``mdump``:
**NOTES:** .. code-block:: shell
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
The following is an example of how to use ``mdump``:
.. code-block:: shell
SHLL [/] $ mdump 0x10000 32 SHLL [/] $ mdump 0x10000 32
0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ 0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
@ -85,223 +84,214 @@ The following is an example of how to use ``mdump``:
0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`.....H.. 0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`.....H..
0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(.. 0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP .. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP
.. index:: CONFIGURE_SHELL_COMMAND_MDUMP .. index:: CONFIGURE_SHELL_COMMAND_MDUMP
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mdump .. index:: rtems_shell_rtems_main_mdump
The ``mdump`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``mdump`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_mdump( int rtems_shell_rtems_main_mdump(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``mdump`` has the following prototype: The configuration structure for the ``mdump`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
.. raw:: latex
\clearpage
.. _wdump: .. _wdump:
wdump - display contents of memory (word) wdump - display contents of memory (word)
----------------------------------------- -----------------------------------------
.. index:: wdump .. index:: wdump
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
wdump [address [length]] wdump [address [length]]
**DESCRIPTION:** DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` in bytes specified on the command line.
This command displays the contents of memory at the ``address`` and ``length`` This command is equivalent to ``mdump address length 2``.
in bytes specified on the command line.
This command is equivalent to ``mdump address length 2``. When ``length`` is not provided, it defaults to ``320`` which is twenty
lines of output with eight words of output per line.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``address`` is not provided, it defaults to ``0x00000000``.
of output with eight words of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. EXIT STATUS:
This command always returns 0 to indicate success.
**EXIT STATUS:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
This command always returns 0 to indicate success. EXAMPLES:
The following is an example of how to use ``wdump``:
**NOTES:** .. code-block:: shell
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
The following is an example of how to use ``wdump``:
.. code-block:: shell
SHLL [/] $ wdump 0x02010000 32 SHLL [/] $ wdump 0x02010000 32
0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...............
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP .. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP
.. index:: CONFIGURE_SHELL_COMMAND_WDUMP .. index:: CONFIGURE_SHELL_COMMAND_WDUMP
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_wdump .. index:: rtems_shell_rtems_main_wdump
The ``wdump`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``wdump`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_wdump( int rtems_shell_rtems_main_wdump(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``wdump`` has the following prototype: The configuration structure for the ``wdump`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
.. raw:: latex
\clearpage
.. _ldump: .. _ldump:
ldump - display contents of memory (longword) ldump - display contents of memory (longword)
--------------------------------------------- ---------------------------------------------
.. index:: ldump .. index:: ldump
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
ldump [address [length]] ldump [address [length]]
**DESCRIPTION:** DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` in bytes specified on the command line.
This command displays the contents of memory at the ``address`` and ``length`` This command is equivalent to ``mdump address length 4``.
in bytes specified on the command line.
This command is equivalent to ``mdump address length 4``. When ``length`` is not provided, it defaults to ``320`` which is twenty
lines of output with four longwords of output per line.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``address`` is not provided, it defaults to ``0x00000000``.
of output with four longwords of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. EXIT STATUS:
This command always returns 0 to indicate success.
**EXIT STATUS:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
This command always returns 0 to indicate success. EXAMPLES:
The following is an example of how to use ``ldump``:
**NOTES:** .. code-block:: shell
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
The following is an example of how to use ``ldump``:
.. code-block:: shell
SHLL [/] $ ldump 0x02010000 32 SHLL [/] $ ldump 0x02010000 32
0x02010000 020108D8 020108C0-020108AC 02010874 ...............t 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t
0x02010010 020 0894 02010718-02010640 02010798 ............... 0x02010010 020 0894 02010718-02010640 02010798 ...............
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP .. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP
.. index:: CONFIGURE_SHELL_COMMAND_LDUMP .. index:: CONFIGURE_SHELL_COMMAND_LDUMP
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ldump .. index:: rtems_shell_rtems_main_ldump
The ``ldump`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``ldump`` is implemented by a C language function which has the following
prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_ldump( int rtems_shell_rtems_main_ldump(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``ldump`` has the following prototype: The configuration structure for the ``ldump`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
.. raw:: latex
\clearpage
.. _medit: .. _medit:
medit - modify contents of memory medit - modify contents of memory
--------------------------------- ---------------------------------
.. index:: medit .. index:: medit
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
medit address value1 [value2 ... valueN] medit address value1 [value2 ... valueN]
**DESCRIPTION:** DESCRIPTION:
This command is used to modify the contents of the memory starting at
``address`` using the octets specified by the parameters``value1`` through
``valueN``.
This command is used to modify the contents of the memory starting at EXIT STATUS:
``address`` using the octets specified by the parameters``value1`` through This command returns 0 on success and non-zero if an error is encountered.
``valueN``.
**EXIT STATUS:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
This command returns 0 on success and non-zero if an error is encountered. EXAMPLES:
The following is an example of how to use ``medit``:
**NOTES:** .. code-block:: shell
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
The following is an example of how to use ``medit``:
.. code-block:: shell
SHLL [/] $ mdump 0x02000000 32 SHLL [/] $ mdump 0x02000000 32
0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
@ -311,78 +301,76 @@ The following is an example of how to use ``medit``:
0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!. 0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!. 0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT .. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT
.. index:: CONFIGURE_SHELL_COMMAND_MEDIT .. index:: CONFIGURE_SHELL_COMMAND_MEDIT
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_medit .. index:: rtems_shell_rtems_main_medit
The ``medit`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``medit`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_medit( int rtems_shell_rtems_main_medit(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``medit`` has the following prototype: The configuration structure for the ``medit`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
.. raw:: latex
\clearpage
.. _mfill: .. _mfill:
mfill - file memory with pattern mfill - file memory with pattern
-------------------------------- --------------------------------
.. index:: mfill .. index:: mfill
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
mfill address length value mfill address length value
**DESCRIPTION:** DESCRIPTION:
This command is used to fill the memory starting at ``address`` for the
specified ``length`` in octets when the specified at``value``.
This command is used to fill the memory starting at ``address`` for the EXIT STATUS:
specified ``length`` in octets when the specified at``value``. This command returns 0 on success and non-zero if an error is encountered.
**EXIT STATUS:** NOTES:
Filling a non-existent address range may result in an unrecoverable program
fault. Similarly overwriting interrupt vector tables, code space or
critical data areas can be fatal as shown in the example.
This command returns 0 on success and non-zero if an error is encountered. EXAMPLES:
In this example, the address used (``0x23d89a0``) as the base address of
the filled area is the end of the stack for the Idle thread. This address
was determined manually using gdb and is very specific to this application
and BSP. The first command in this example is an ``mdump`` to display the
initial contents of this memory. We see that the first 8 bytes are 0xA5
which is the pattern used as a guard by the Stack Checker. On the first
context switch after the pattern is overwritten by the ``mfill`` command,
the Stack Checker detect the pattern has been corrupted and generates a
fatal error.
**NOTES:** .. code-block:: shell
Filling a non-existent address range may result in an unrecoverable program
fault. Similarly overwriting interrupt vector tables, code space or critical
data areas can be fatal as shown in the example.
**EXAMPLES:**
In this example, the address used (``0x23d89a0``) as the base address of the
filled area is the end of the stack for the Idle thread. This address was
determined manually using gdb and is very specific to this application and BSP.
The first command in this example is an ``mdump`` to display the initial
contents of this memory. We see that the first 8 bytes are 0xA5 which is the
pattern used as a guard by the Stack Checker. On the first context switch
after the pattern is overwritten by the ``mfill`` command, the Stack Checker
detect the pattern has been corrupted and generates a fatal error.
.. code-block:: shell
SHLL [/] $ mdump 0x23d89a0 16 SHLL [/] $ mdump 0x23d89a0 16
0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................ 0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
@ -391,70 +379,67 @@ detect the pattern has been corrupted and generates a fatal error.
stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes) stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
Damaged pattern begins at 0x023D89A8 and is 16 bytes long Damaged pattern begins at 0x023D89A8 and is 16 bytes long
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL .. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL
.. index:: CONFIGURE_SHELL_COMMAND_MFILL .. index:: CONFIGURE_SHELL_COMMAND_MFILL
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mfill .. index:: rtems_shell_rtems_main_mfill
The ``mfill`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``mfill`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_mfill( int rtems_shell_rtems_main_mfill(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``mfill`` has the The configuration structure for the ``mfill`` has the
following prototype: following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_MFILL_Command; extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
.. raw:: latex
\clearpage
.. _mmove: .. _mmove:
mmove - move contents of memory mmove - move contents of memory
------------------------------- -------------------------------
.. index:: mmove .. index:: mmove
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
mmove dst src length mmove dst src length
**DESCRIPTION:** DESCRIPTION:
This command is used to copy the contents of the memory starting at ``src``
to the memory located at ``dst`` for the specified ``length`` in octets.
This command is used to copy the contents of the memory starting at ``src`` to EXIT STATUS:
the memory located at ``dst`` for the specified ``length`` in octets. This command returns 0 on success and non-zero if an error is encountered.
**EXIT STATUS:** NOTES:
NONE
This command returns 0 on success and non-zero if an error is encountered. EXAMPLES:
The following is an example of how to use ``mmove``:
**NOTES:** .. code-block:: shell
NONE
**EXAMPLES:**
The following is an example of how to use ``mmove``:
.. code-block:: shell
SHLL [/] $ mdump 0x023d99a0 16 SHLL [/] $ mdump 0x023d99a0 16
0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................ 0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
@ -464,107 +449,104 @@ The following is an example of how to use ``mmove``:
SHLL [/] $ mdump 0x023d99a0 16 SHLL [/] $ mdump 0x023d99a0 16
0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3.."..... 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE .. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE
.. index:: CONFIGURE_SHELL_COMMAND_MMOVE .. index:: CONFIGURE_SHELL_COMMAND_MMOVE
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mmove .. index:: rtems_shell_rtems_main_mmove
The ``mmove`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``mmove`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_mmove( int rtems_shell_rtems_main_mmove(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``mmove`` has the following prototype: The configuration structure for the ``mmove`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
.. raw:: latex
\clearpage
.. _malloc: .. _malloc:
malloc - obtain information on C program heap malloc - obtain information on C program heap
--------------------------------------------- ---------------------------------------------
.. index:: malloc .. index:: malloc
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
malloc [walk] malloc [walk]
**DESCRIPTION:** DESCRIPTION:
This command prints information about the current state of the C Program
Heap used by the ``malloc()`` family of calls if no or invalid options are
passed to the command. This includes the following information:
This command prints information about the current state of the C Program Heap - Number of free blocks
used by the ``malloc()`` family of calls if no or invalid options are passed to
the command. This includes the following information:
- Number of free blocks - Largest free block
- Largest free block - Total bytes free
- Total bytes free - Number of used blocks
- Number of used blocks - Largest used block
- Largest used block - Total bytes used
- Total bytes used - Size of the allocatable area in bytes
- Size of the allocatable area in bytes - Minimum free size ever in bytes
- Minimum free size ever in bytes - Maximum number of free blocks ever
- Maximum number of free blocks ever - Maximum number of blocks searched ever
- Maximum number of blocks searched ever - Lifetime number of bytes allocated
- Lifetime number of bytes allocated - Lifetime number of bytes freed
- Lifetime number of bytes freed - Total number of searches
- Total number of searches - Total number of successful allocations
- Total number of successful allocations - Total number of failed allocations
- Total number of failed allocations - Total number of successful frees
- Total number of successful frees - Total number of successful resizes
- Total number of successful resizes When the subcommand ``walk`` is specified, then a heap walk will be
performed and information about each block is printed out.
When the subcommand ``walk`` is specified, then a heap walk will be performed EXIT STATUS:
and information about each block is printed out. This command returns 0 on success and non-zero if an error is encountered.
**EXIT STATUS:** NOTES:
NONE
This command returns 0 on success and non-zero if an error is encountered. EXAMPLES:
The following is an example of how to use the ``malloc`` command.
**NOTES:** .. code-block:: shell
NONE
**EXAMPLES:**
The following is an example of how to use the ``malloc`` command.
.. code-block:: shell
SHLL [/] $ malloc SHLL [/] $ malloc
C Program Heap and RTEMS Workspace are the same. C Program Heap and RTEMS Workspace are the same.
@ -605,35 +587,33 @@ The following is an example of how to use the ``malloc`` command.
PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail) PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail)
PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192 PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC .. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC
.. index:: CONFIGURE_SHELL_COMMAND_MALLOC .. index:: CONFIGURE_SHELL_COMMAND_MALLOC
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_malloc .. index:: rtems_shell_rtems_main_malloc
The ``malloc`` is implemented by a C language function PROGRAMMING INFORMATION:
which has the following prototype: The ``malloc`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_malloc( int rtems_shell_rtems_main_malloc(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``malloc`` has the following prototype: The configuration structure for the ``malloc`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;

564
shell/network_commands.rst
View File

@ -27,62 +27,61 @@ This section details the Network Commands available. A subsection is dedicated
to each of the commands and describes the behavior and configuration of that to each of the commands and describes the behavior and configuration of that
command as well as providing an example usage. command as well as providing an example usage.
.. raw:: latex
\clearpage
.. _netstats: .. _netstats:
netstats - obtain network statistics netstats - obtain network statistics
------------------------------------ ------------------------------------
.. index:: netstats .. index:: netstats
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
netstats [-Aimfpcut] netstats [-Aimfpcut]
**DESCRIPTION:** DESCRIPTION:
This command is used to display various types of network statistics. The
information displayed can be specified using command line arguments in
various combinations. The arguments are interpreted as follows:
This command is used to display various types of network statistics. The *-A*
information displayed can be specified using command line arguments in various
combinations. The arguments are interpreted as follows:
*-A*
print All statistics print All statistics
*-i* *-i*
print Inet Routes print Inet Routes
*-m* *-m*
print MBUF Statistics print MBUF Statistics
*-f* *-f*
print IF Statistics print IF Statistics
*-p* *-p*
print IP Statistics print IP Statistics
*-c* *-c*
print ICMP Statistics print ICMP Statistics
*-u* *-u*
print UDP Statistics print UDP Statistics
*-t* *-t*
print TCP Statistics print TCP Statistics
**EXIT STATUS:** EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
This command returns 0 on success and non-zero if an error is encountered. NOTES:
NONE
**NOTES:** EXAMPLES:
The following is an example of using the ``netstats`` command to print the
IP routing table:
NONE .. code-block:: shell
**EXAMPLES:**
The following is an example of using the ``netstats`` command to print the IP
routing table:
.. code-block:: shell
[/] $ netstats -i [/] $ netstats -i
Destination Gateway/Mask/Hw Flags Refs Use Expire Interface Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
@ -92,10 +91,10 @@ routing table:
192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 840 1202 eth1 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 840 1202 eth1
192.168.1.151 00:1C:23:B2:0F:BB UHL 1 23 1219 eth1 192.168.1.151 00:1C:23:B2:0F:BB UHL 1 23 1219 eth1
The following is an example of using the ``netstats`` command to print the MBUF The following is an example of using the ``netstats`` command to print the
statistics: MBUF statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -m [/] $ netstats -m
************ MBUF STATISTICS ************ ************ MBUF STATISTICS ************
@ -106,10 +105,10 @@ statistics:
soname:0 soopts:0 ftable:0 rights:0 soname:0 soopts:0 ftable:0 rights:0
ifaddr:0 control:0 oobdata:0 ifaddr:0 control:0 oobdata:0
The following is an example of using the ``netstats`` command to print the The following is an example of using the ``netstats`` command to print the
print the interface statistics: print the interface statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -f [/] $ netstats -f
************ INTERFACE STATISTICS ************ ************ INTERFACE STATISTICS ************
@ -124,10 +123,10 @@ print the interface statistics:
Tx Interrupts:867 Deferred:0 Late Collision:0 Tx Interrupts:867 Deferred:0 Late Collision:0
Retransmit Limit:0 Underrun:0 Misaligned:0 Retransmit Limit:0 Underrun:0 Misaligned:0
The following is an example of using the ``netstats`` command to print the The following is an example of using the ``netstats`` command to print the
print IP statistics: print IP statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -p [/] $ netstats -p
************ IP Statistics ************ ************ IP Statistics ************
@ -136,10 +135,10 @@ print IP statistics:
datagrams delivered to upper level 881 datagrams delivered to upper level 881
total ip packets generated here 871 total ip packets generated here 871
The following is an example of using the ``netstats`` command to print the ICMP The following is an example of using the ``netstats`` command to print the
statistics: ICMP statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -c [/] $ netstats -c
************ ICMP Statistics ************ ************ ICMP Statistics ************
@ -147,18 +146,18 @@ statistics:
number of responses 843 number of responses 843
Type 8 received 843 Type 8 received 843
The following is an example of using the ``netstats`` command to print the UDP The following is an example of using the ``netstats`` command to print the
statistics: UDP statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -u [/] $ netstats -u
************ UDP Statistics ************ ************ UDP Statistics ************
The following is an example of using the ``netstats`` command to print the TCP The following is an example of using the ``netstats`` command to print the
statistics: TCP statistics:
.. code-block:: shell .. code-block:: shell
[/] $ netstats -t [/] $ netstats -t
************ TCP Statistics ************ ************ TCP Statistics ************
@ -179,73 +178,70 @@ statistics:
times hdr predict ok for acks 27 times hdr predict ok for acks 27
times hdr predict ok for data pkts 10 times hdr predict ok for data pkts 10
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS .. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS
.. index:: CONFIGURE_SHELL_COMMAND_NETSTATS .. index:: CONFIGURE_SHELL_COMMAND_NETSTATS
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have
this command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_netstats .. index:: rtems_shell_rtems_main_netstats
The ``netstats`` is implemented by a C language function PROGRAMMING INFORMATION:
which has the following prototype: The ``netstats`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_netstats( int rtems_shell_rtems_main_netstats(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``netstats`` has the following prototype: The configuration structure for the ``netstats`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command;
.. raw:: latex
\clearpage
.. _ifconfig: .. _ifconfig:
ifconfig - configure a network interface ifconfig - configure a network interface
---------------------------------------- ----------------------------------------
.. index:: ifconfig .. index:: ifconfig
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
ifconfig ifconfig
ifconfig interface ifconfig interface
ifconfig interface \[up|down] ifconfig interface \[up|down]
ifconfig interface \[netmask|pointtopoint|broadcast] IP ifconfig interface \[netmask|pointtopoint|broadcast] IP
**DESCRIPTION:** DESCRIPTION:
This command may be used to display information about the network
interfaces in the system or configure them.
This command may be used to display information about the network interfaces in EXIT STATUS:
the system or configure them. This command returns 0 on success and non-zero if an error is encountered.
**EXIT STATUS:** NOTES:
Just like its counterpart on GNU/Linux and BSD systems, this command is
complicated. More example usages would be a welcome submission.
This command returns 0 on success and non-zero if an error is encountered. EXAMPLES:
The following is an example of how to use ``ifconfig``:
**NOTES:** .. code-block:: shell
Just like its counterpart on GNU/Linux and BSD systems, this command is
complicated. More example usages would be a welcome submission.
**EXAMPLES:**
The following is an example of how to use ``ifconfig``:
.. code-block:: shell
************ INTERFACE STATISTICS ************ ************ INTERFACE STATISTICS ************
***** eth1 ***** ***** eth1 *****
@ -259,82 +255,80 @@ The following is an example of how to use ``ifconfig``:
Tx Interrupts:5256 Deferred:0 Late Collision:0 Tx Interrupts:5256 Deferred:0 Late Collision:0
Retransmit Limit:0 Underrun:0 Misaligned:0 Retransmit Limit:0 Underrun:0 Misaligned:0
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG .. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
.. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG .. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have
this command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ifconfig .. index:: rtems_shell_rtems_main_ifconfig
The ``ifconfig`` is implemented by a C language function which has the PROGRAMMING INFORMATION:
following prototype: The ``ifconfig`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_ifconfig( int rtems_shell_rtems_main_ifconfig(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``ifconfig`` has the following prototype: The configuration structure for the ``ifconfig`` has the following
prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
.. raw:: latex
\clearpage
.. _route: .. _route:
route - show or manipulate the ip routing table route - show or manipulate the ip routing table
----------------------------------------------- -----------------------------------------------
.. index:: route .. index:: route
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
route [subcommand] [args] route [subcommand] [args]
**DESCRIPTION:** DESCRIPTION:
This command is used to display and manipulate the routing table. When
invoked with no arguments, the current routing information is displayed.
When invoked with the subcommands ``add`` or ``del``, then additional
arguments must be provided to describe the route.
This command is used to display and manipulate the routing table. When invoked Command templates include the following:
with no arguments, the current routing information is displayed. When invoked
with the subcommands ``add`` or ``del``, then additional arguments must be
provided to describe the route.
Command templates include the following: .. code-block:: shell
.. code-block:: shell
route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK] route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK]
route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK] route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK]
When not provided the netmask defaults to ``255.255.255.0`` When not provided the netmask defaults to ``255.255.255.0``
**EXIT STATUS:** EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
This command returns 0 on success and non-zero if an error is encountered. NOTES:
Just like its counterpart on GNU/Linux and BSD systems, this command is
complicated. More example usages would be a welcome submission.
**NOTES:** EXAMPLES:
The following is an example of how to use ``route`` to display, add, and
delete a new route:
Just like its counterpart on GNU/Linux and BSD systems, this command is .. code-block:: shell
complicated. More example usages would be a welcome submission.
**EXAMPLES:**
The following is an example of how to use ``route`` to display, add, and delete
a new route:
.. code-block:: shell
[/] $ route [/] $ route
Destination Gateway/Mask/Hw Flags Refs Use Expire Interface Destination Gateway/Mask/Hw Flags Refs Use Expire Interface
@ -361,48 +355,49 @@ a new route:
192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 15945 1202 eth1 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 15945 1202 eth1
192.168.1.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE .. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE
.. index:: CONFIGURE_SHELL_COMMAND_ROUTE .. index:: CONFIGURE_SHELL_COMMAND_ROUTE
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_route .. index:: rtems_shell_rtems_main_route
The ``route`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``route`` is implemented by a C language function which has the
following prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_route( int rtems_shell_rtems_main_route(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``route`` has the following prototype: The configuration structure for the ``route`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; extern rtems_shell_cmd_t rtems_shell_ROUTE_Command;
.. raw:: latex
\clearpage
.. _ping: .. _ping:
ping - ping a host or IP address ping - ping a host or IP address
-------------------------------- --------------------------------
.. index:: ping .. index:: ping
**SYNOPSYS:** SYNOPSYS:
.. code-block:: shell
.. code-block:: shell
ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize] ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize]
[-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl] [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl]
@ -413,195 +408,196 @@ ping - ping a host or IP address
[-s packetsize] [-T ttl] [-t timeout] [-W waittime] [-s packetsize] [-T ttl] [-t timeout] [-W waittime]
[-z tos] mcast-group [-z tos] mcast-group
**DESCRIPTION:** DESCRIPTION:
The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST datagram
to elicit an ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST
datagrams ("pings") have an IP and ICMP header, followed by a "struct
timeval" and then an arbitrary number of "pad" bytes used to fill out the
packet. The options are as follows:
The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST datagram to *-A*
elicit an ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams Audible. Output a bell (ASCII 0x07) character when no packet is
("pings") have an IP and ICMP header, followed by a "struct timeval" and then received before the next packet is transmitted. To cater for
an arbitrary number of "pad" bytes used to fill out the packet. The options round-trip times that are longer than the interval between
are as follows: transmissions, further missing packets cause a bell only if the maximum
number of unreceived packets has increased.
*-A* *-a*
Audible. Output a bell (ASCII 0x07) character when no packet is received
before the next packet is transmitted. To cater for round-trip times that
are longer than the interval between transmissions, further missing packets
cause a bell only if the maximum number of unreceived packets has
increased.
*-a*
Audible. Include a bell (ASCII 0x07) character in the output when any Audible. Include a bell (ASCII 0x07) character in the output when any
packet is received. This option is ignored if other format options are packet is received. This option is ignored if other format options are
present. present.
*-c count* *-c count*
Stop after sending (and receiving) count ECHO_RESPONSE packets. If this Stop after sending (and receiving) count ECHO_RESPONSE packets. If
option is not specified, ping will operate until interrupted. If this this option is not specified, ping will operate until interrupted. If
option is specified in conjunction with ping sweeps, each sweep will this option is specified in conjunction with ping sweeps, each sweep
consist of count packets. will consist of count packets.
*-D* *-D*
Set the Don't Fragment bit. Set the Don't Fragment bit.
*-d* *-d*
Set the SO_DEBUG option on the socket being used. Set the SO_DEBUG option on the socket being used.
*-f* *-f*
Flood ping. Outputs packets as fast as they come back or one hundred times Flood ping. Outputs packets as fast as they come back or one hundred
per second, whichever is more. For every ECHO_REQUEST sent a period "." is times per second, whichever is more. For every ECHO_REQUEST sent a
printed, while for every ECHO_REPLY received a backspace is printed. This period "." is printed, while for every ECHO_REPLY received a backspace
provides a rapid display of how many packets are being dropped. Only the is printed. This provides a rapid display of how many packets are
super-user may use this option. This can be very hard on a network and being dropped. Only the super-user may use this option. This can be
should be used with caution. very hard on a network and should be used with caution.
*-G sweepmaxsize* *-G sweepmaxsize*
Specify the maximum size of ICMP payload when sending sweeping pings. This Specify the maximum size of ICMP payload when sending sweeping pings.
option is required for ping sweeps. This option is required for ping sweeps.
*-g sweepminsize* *-g sweepminsize*
Specify the size of ICMP payload to start with when sending sweeping pings. Specify the size of ICMP payload to start with when sending sweeping
The default value is 0. pings. The default value is 0.
*-h sweepincrsize* *-h sweepincrsize*
Specify the number of bytes to increment the size of ICMP payload after Specify the number of bytes to increment the size of ICMP payload after
each sweep when sending sweeping pings. The default value is 1. each sweep when sending sweeping pings. The default value is 1.
*-I iface* *-I iface*
Source multicast packets with the given interface address. This flag only Source multicast packets with the given interface address. This flag
applies if the ping destination is a multicast address. only applies if the ping destination is a multicast address.
*-i wait* *-i wait*
Wait wait seconds between sending each packet. The default is to wait for Wait wait seconds between sending each packet. The default is to wait
one second between each packet. The wait time may be fractional, but only for one second between each packet. The wait time may be fractional,
the super-user may specify values less than 1 second. This option is but only the super-user may specify values less than 1 second. This
incompatible with the -f option. option is incompatible with the -f option.
*-L* *-L*
Suppress loopback of multicast packets. This flag only applies if the ping Suppress loopback of multicast packets. This flag only applies if the
destination is a multicast address. ping destination is a multicast address.
*-l preload* *-l preload*
If preload is specified, ping sends that many packets as fast as possible If preload is specified, ping sends that many packets as fast as
before falling into its normal mode of behavior. Only the super-user may possible before falling into its normal mode of behavior. Only the
use this option. super-user may use this option.
*-M mask | time* *-M mask | time*
Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO. For mask, print the Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO. For mask, print
netmask of the remote machine. Set the net.inet.icmp.maskrepl MIB variable the netmask of the remote machine. Set the net.inet.icmp.maskrepl MIB
to enable ICMP_MASKREPLY. For time, print the origination, reception and variable to enable ICMP_MASKREPLY. For time, print the origination,
transmission timestamps. reception and transmission timestamps.
*-m ttl* *-m ttl*
Set the IP Time To Live for outgoing packets. If not specified, the kernel Set the IP Time To Live for outgoing packets. If not specified, the
uses the value of the net.inet.ip.ttl MIB variable. kernel uses the value of the net.inet.ip.ttl MIB variable.
*-n* *-n*
Numeric output only. No attempt will be made to lookup symbolic names for Numeric output only. No attempt will be made to lookup symbolic names
host addresses. for host addresses.
*-o* *-o*
Exit successfully after receiving one reply packet. Exit successfully after receiving one reply packet.
*-p pattern* *-p pattern*
You may specify up to 16 "pad" bytes to fill out the packet you send. This You may specify up to 16 "pad" bytes to fill out the packet you send.
is useful for diagnosing data-dependent problems in a network. For This is useful for diagnosing data-dependent problems in a network.
example, "-p ff" will cause the sent packet to be filled with all ones. For example, "-p ff" will cause the sent packet to be filled with all
ones.
*-Q* *-Q*
Somewhat quiet output. Don't display ICMP error messages that are in Somewhat quiet output. Don't display ICMP error messages that are in
response to our query messages. Originally, the -v flag was required to response to our query messages. Originally, the -v flag was required
display such errors, but -v displays all ICMP error messages. On a busy to display such errors, but -v displays all ICMP error messages. On a
machine, this output can be overbear- ing. Without the -Q flag, ping busy machine, this output can be overbear- ing. Without the -Q flag,
prints out any ICMP error mes- sages caused by its own ECHO_REQUEST ping prints out any ICMP error mes- sages caused by its own
messages. ECHO_REQUEST messages.
*-q* *-q*
Quiet output. Nothing is displayed except the summary lines at startup Quiet output. Nothing is displayed except the summary lines at startup
time and when finished. time and when finished.
*-R* *-R*
Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST packet Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST
and displays the route buffer on returned packets. Note that the IP header packet and displays the route buffer on returned packets. Note that
is only large enough for nine such routes; the traceroute(8) command is the IP header is only large enough for nine such routes; the
usually better at determining the route packets take to a particular traceroute(8) command is usually better at determining the route
destination. If more routes come back than should, such as due to an packets take to a particular destination. If more routes come back
illegal spoofed packet, ping will print the route list and then truncate it than should, such as due to an illegal spoofed packet, ping will print
at the correct spot. Many hosts ignore or discard the RECORD_ROUTE option. the route list and then truncate it at the correct spot. Many hosts
ignore or discard the RECORD_ROUTE option.
*-r* *-r*
Bypass the normal routing tables and send directly to a host on an attached Bypass the normal routing tables and send directly to a host on an
network. If the host is not on a directly-attached network, an error is attached network. If the host is not on a directly-attached network,
returned. This option can be used to ping a local host through an an error is returned. This option can be used to ping a local host
interface that has no route through it (e.g., after the interface was through an interface that has no route through it (e.g., after the
dropped). interface was dropped).
*-S src_addr* *-S src_addr*
Use the following IP address as the source address in outgoing packets. On Use the following IP address as the source address in outgoing packets.
hosts with more than one IP address, this option can be used to force the On hosts with more than one IP address, this option can be used to
source address to be something other than the IP address of the interface force the source address to be something other than the IP address of
the probe packet is sent on. If the IP address is not one of this the interface the probe packet is sent on. If the IP address is not
machine's interface addresses, an error is returned and nothing is sent. one of this machine's interface addresses, an error is returned and
nothing is sent.
*-s packetsize* *-s packetsize*
Specify the number of data bytes to be sent. The default is 56, which Specify the number of data bytes to be sent. The default is 56, which
translates into 64 ICMP data bytes when combined with the 8 bytes of ICMP translates into 64 ICMP data bytes when combined with the 8 bytes of
header data. Only the super-user may specify val- ues more than default. ICMP header data. Only the super-user may specify val- ues more than
This option cannot be used with ping sweeps. default. This option cannot be used with ping sweeps.
*-T ttl* *-T ttl*
Set the IP Time To Live for multicasted packets. This flag only applies if Set the IP Time To Live for multicasted packets. This flag only
the ping destination is a multicast address. applies if the ping destination is a multicast address.
*-t timeout* *-t timeout*
Specify a timeout, in seconds, before ping exits regardless of how many Specify a timeout, in seconds, before ping exits regardless of how many
packets have been received. packets have been received.
*-v* *-v*
Verbose output. ICMP packets other than ECHO_RESPONSE that are received Verbose output. ICMP packets other than ECHO_RESPONSE that are
are listed. received are listed.
*-W waittime* *-W waittime*
Time in milliseconds to wait for a reply for each packet sent. If a reply Time in milliseconds to wait for a reply for each packet sent. If a
arrives later, the packet is not printed as replied, but considered as reply arrives later, the packet is not printed as replied, but
replied when calculating statistics. considered as replied when calculating statistics.
*-z tos* *-z tos*
Use the specified type of service. Use the specified type of service.
**EXIT STATUS:** EXIT STATUS:
The ping utility exits with one of the following values:
The ping utility exits with one of the following values: 0 At least one response was heard from the specified host.
0 At least one response was heard from the specified host. 2 The transmission was successful but no responses were
2 The transmission was successful but no responses were
received. received.
any other value an error occurred. These values are defined in <sysexits.h>. any other value an error occurred. These values are defined in
<sysexits.h>.
**NOTES:** NOTES:
When using ping for fault isolation, it should first be run on the local
host, to verify that the local network interface is up and running. Then,
hosts and gateways further and further away should be "pinged". Round-trip
times and packet loss statistics are computed. If duplicate packets are
received, they are not included in the packet loss calculation, although
the round trip time of these packets is used in calculating the round-trip
time statistics. When the specified number of packets have been sent a
brief summary is displayed, showing the number of packets sent and
received, and the minimum, mean, maximum, and standard deviation of the
round-trip times.
When using ping for fault isolation, it should first be run on the local host, This program is intended for use in network testing, measurement and
to verify that the local network interface is up and running. Then, hosts and management. Because of the load it can impose on the network, it is unwise
gateways further and further away should be "pinged". Round-trip times and to use ping during normal operations or from automated scripts.
packet loss statistics are computed. If duplicate packets are received, they
are not included in the packet loss calculation, although the round trip time
of these packets is used in calculating the round-trip time statistics. When
the specified number of packets have been sent a brief summary is displayed,
showing the number of packets sent and received, and the minimum, mean,
maximum, and standard deviation of the round-trip times.
This program is intended for use in network testing, measurement and This command can fail if more than the FD_SET size number of file
management. Because of the load it can impose on the network, it is unwise to descriptors are open.
use ping during normal operations or from automated scripts.
This command can fail if more than the FD_SET size number of file descriptors EXAMPLES:
are open. The following is an example of how to use ``oing`` to ping:
**EXAMPLES:** .. code-block:: shell
The following is an example of how to use ``oing`` to ping:
.. code-block:: shell
[/] # ping 10.10.10.1 [/] # ping 10.10.10.1
PING 10.10.10.1 (10.10.10.1): 56 data bytes PING 10.10.10.1 (10.10.10.1): 56 data bytes
@ -620,35 +616,33 @@ The following is an example of how to use ``oing`` to ping:
10000 packets transmitted, 10000 packets received, 0.0% packet loss 10000 packets transmitted, 10000 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_PING .. index:: CONFIGURE_SHELL_NO_COMMAND_PING
.. index:: CONFIGURE_SHELL_COMMAND_PING .. index:: CONFIGURE_SHELL_COMMAND_PING
This command is included in the default shell command set. When building a CONFIGURATION:
custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this This command is included in the default shell command set. When building a
command included. custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this
command included.
This command can be excluded from the shell command set by defining This command can be excluded from the shell command set by defining
``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been ``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been
configured. configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ping .. index:: rtems_shell_rtems_main_ping
The ``ping`` is implemented by a C language function which has the following PROGRAMMING INFORMATION:
prototype: The ``ping`` is implemented by a C language function which has the following
prototype:
.. code-block:: c .. code-block:: c
int rtems_shell_rtems_main_ping( int rtems_shell_rtems_main_ping(
int argc, int argc,
char **argv char **argv
); );
The configuration structure for the ``ping`` has the following prototype: The configuration structure for the ``ping`` has the following prototype:
.. code-block:: c .. code-block:: c
extern rtems_shell_cmd_t rtems_shell_PING_Command; extern rtems_shell_cmd_t rtems_shell_PING_Command;

1179
shell/rtems_specific_commands.rst
View File

File diff suppressed because it is too large Load Diff