rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 20:29:22 +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

63
shell/configuration_and_init.rst
View File

@ -296,14 +296,16 @@ 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
CALLING SEQUENCE:
.. code-block:: c .. code-block:: c
rtems_status_code rtems_shell_init( rtems_status_code rtems_shell_init(
@ -316,35 +318,33 @@ 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 ``RTEMS_SUCCESSFUL`` - Shell task spawned successfully
*others* - to indicate a failure condition
others - to indicate a failure condition DESCRIPTION:
**DESCRIPTION:**
This service creates a task with the specified characteristics to run the RTEMS This service creates a task with the specified characteristics to run the RTEMS
Shell attached to the specified ``devname``. Shell attached to the specified ``devname``.
**NOTES:** NOTES:
This method invokes the ``rtems_task_create`` and ``rtems_task_start`` This method invokes the ``rtems_task_create`` and ``rtems_task_start``
directives and as such may return any status code that those directives may directives and as such may return any status code that those directives may
return. return.
There is one POSIX key necessary for all shell instances together and one POSIX There is one POSIX key necessary for all shell instances together and one
key value pair per instance. You should make sure that your RTEMS configuration POSIX key value pair per instance. You should make sure that your RTEMS
accounts for these resources. configuration accounts for these resources.
.. raw:: latex
\clearpage
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
CALLING SEQUENCE:
.. code:: c .. code:: c
bool rtems_shell_login_check( bool rtems_shell_login_check(
@ -352,35 +352,32 @@ rtems_shell_login_check - Default login check handler
const char *passphrase const char *passphrase
); );
**DIRECTIVE STATUS CODES:** DIRECTIVE STATUS CODES:
``true`` - login is allowed, and ``true`` - login is allowed, and
``false`` - otherwise. ``false`` - otherwise.
**DESCRIPTION:** DESCRIPTION:
This function checks if the specified passphrase is valid for the specified This function checks if the specified passphrase is valid for the specified
user. user.
**NOTES:** NOTES:
As a side-effect if the specified passphrase is valid for the specified
user, this function:
As a side-effect if the specified passphrase is valid for the specified user, - performs a filesystem change root operation to the directory of the
this function: specified user if the directory path is non-empty,
- 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 - 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.

1523
shell/file_and_directory.rst
View File

File diff suppressed because it is too large Load Diff

624
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

258
shell/memory_commands.rst
View File

@ -34,43 +34,42 @@ 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
This command displays the contents of memory at the ``address`` and ``length`` ``length`` in ``size`` byte units specified on the command line.
in ``size`` byte units specified on the command line.
When ``size`` is not provided, it defaults to ``1`` byte units. Values of When ``size`` is not provided, it defaults to ``1`` byte units. Values of
``1``, ``2``, and ``4`` are valid; all others will cause an error to be ``1``, ``2``, and ``4`` are valid; all others will cause an error to be
reported. reported.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``length`` is not provided, it defaults to ``320`` which is twenty
of output with sixteen bytes of output per line. lines of output with sixteen bytes of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:** EXIT STATUS:
This command always returns 0 to indicate success. This command always returns 0 to indicate success.
**NOTES:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable Dumping memory from a non-existent address may result in an unrecoverable
program fault. program fault.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``mdump``: The following is an example of how to use ``mdump``:
.. code-block:: shell .. code-block:: shell
@ -85,11 +84,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
command included. command included.
@ -98,12 +96,11 @@ 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
@ -118,41 +115,40 @@ The configuration structure for the ``mdump`` has the following prototype:
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
This command displays the contents of memory at the ``address`` and ``length`` ``length`` in bytes specified on the command line.
in bytes specified on the command line.
This command is equivalent to ``mdump address length 2``. This command is equivalent to ``mdump address length 2``.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``length`` is not provided, it defaults to ``320`` which is twenty
of output with eight words of output per line. lines of output with eight words of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:** EXIT STATUS:
This command always returns 0 to indicate success. This command always returns 0 to indicate success.
**NOTES:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable Dumping memory from a non-existent address may result in an unrecoverable
program fault. program fault.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``wdump``: The following is an example of how to use ``wdump``:
.. code-block:: shell .. code-block:: shell
@ -161,11 +157,10 @@ The following is an example of how to use ``wdump``:
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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
command included. command included.
@ -174,12 +169,11 @@ 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
@ -194,41 +188,40 @@ The configuration structure for the ``wdump`` has the following prototype:
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
This command displays the contents of memory at the ``address`` and ``length`` ``length`` in bytes specified on the command line.
in bytes specified on the command line.
This command is equivalent to ``mdump address length 4``. This command is equivalent to ``mdump address length 4``.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines When ``length`` is not provided, it defaults to ``320`` which is twenty
of output with four longwords of output per line. lines of output with four longwords of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``. When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:** EXIT STATUS:
This command always returns 0 to indicate success. This command always returns 0 to indicate success.
**NOTES:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable Dumping memory from a non-existent address may result in an unrecoverable
program fault. program fault.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``ldump``: The following is an example of how to use ``ldump``:
.. code-block:: shell .. code-block:: shell
@ -237,11 +230,10 @@ The following is an example of how to use ``ldump``:
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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
command included. command included.
@ -250,10 +242,9 @@ 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
PROGRAMMING INFORMATION:
The ``ldump`` is implemented by a C language function which has the following The ``ldump`` is implemented by a C language function which has the following
prototype: prototype:
@ -270,35 +261,34 @@ The configuration structure for the ``ldump`` has the following prototype:
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 This command is used to modify the contents of the memory starting at
``address`` using the octets specified by the parameters``value1`` through ``address`` using the octets specified by the parameters``value1`` through
``valueN``. ``valueN``.
**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:** NOTES:
Dumping memory from a non-existent address may result in an unrecoverable Dumping memory from a non-existent address may result in an unrecoverable
program fault. program fault.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``medit``: The following is an example of how to use ``medit``:
.. code-block:: shell .. code-block:: shell
@ -311,11 +301,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
command included. command included.
@ -324,12 +313,11 @@ 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
@ -344,43 +332,43 @@ The configuration structure for the ``medit`` has the following prototype:
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 This command is used to fill the memory starting at ``address`` for the
specified ``length`` in octets when the specified at``value``. specified ``length`` in octets when the specified at``value``.
**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:** NOTES:
Filling a non-existent address range may result in an unrecoverable program Filling a non-existent address range may result in an unrecoverable program
fault. Similarly overwriting interrupt vector tables, code space or critical fault. Similarly overwriting interrupt vector tables, code space or
data areas can be fatal as shown in the example. critical data areas can be fatal as shown in the example.
**EXAMPLES:** EXAMPLES:
In this example, the address used (``0x23d89a0``) as the base address of
In this example, the address used (``0x23d89a0``) as the base address of the the filled area is the end of the stack for the Idle thread. This address
filled area is the end of the stack for the Idle thread. This address was was determined manually using gdb and is very specific to this application
determined manually using gdb and is very specific to this application and BSP. and BSP. The first command in this example is an ``mdump`` to display the
The first command in this example is an ``mdump`` to display the initial initial contents of this memory. We see that the first 8 bytes are 0xA5
contents of this memory. We see that the first 8 bytes are 0xA5 which is the which is the pattern used as a guard by the Stack Checker. On the first
pattern used as a guard by the Stack Checker. On the first context switch context switch after the pattern is overwritten by the ``mfill`` command,
after the pattern is overwritten by the ``mfill`` command, the Stack Checker the Stack Checker detect the pattern has been corrupted and generates a
detect the pattern has been corrupted and generates a fatal error. fatal error.
.. code-block:: shell .. code-block:: shell
@ -391,11 +379,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
command included. command included.
@ -404,12 +391,11 @@ 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
@ -425,33 +411,32 @@ following prototype:
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``
This command is used to copy the contents of the memory starting at ``src`` to to the memory located at ``dst`` for the specified ``length`` in octets.
the memory located at ``dst`` for the specified ``length`` in octets.
**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:** NOTES:
NONE NONE
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``mmove``: The following is an example of how to use ``mmove``:
.. code-block:: shell .. code-block:: shell
@ -464,11 +449,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
command included. command included.
@ -477,12 +461,11 @@ 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
@ -497,23 +480,25 @@ The configuration structure for the ``mmove`` has the following prototype:
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
This command prints information about the current state of the C Program Heap Heap used by the ``malloc()`` family of calls if no or invalid options are
used by the ``malloc()`` family of calls if no or invalid options are passed to passed to the command. This includes the following information:
the command. This includes the following information:
- Number of free blocks - Number of free blocks
@ -549,19 +534,16 @@ the command. This includes the following information:
- Total number of successful resizes - Total number of successful resizes
When the subcommand ``walk`` is specified, then a heap walk will be performed When the subcommand ``walk`` is specified, then a heap walk will be
and information about each block is printed out. performed and information about each block is printed out.
**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:** NOTES:
NONE NONE
**EXAMPLES:** EXAMPLES:
The following is an example of how to use the ``malloc`` command. The following is an example of how to use the ``malloc`` command.
.. code-block:: shell .. code-block:: shell
@ -605,11 +587,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
command included. command included.
@ -618,12 +599,11 @@ 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

348
shell/network_commands.rst
View File

@ -27,23 +27,25 @@ 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 This command is used to display various types of network statistics. The
information displayed can be specified using command line arguments in various information displayed can be specified using command line arguments in
combinations. The arguments are interpreted as follows: various combinations. The arguments are interpreted as follows:
*-A* *-A*
print All statistics print All statistics
@ -69,18 +71,15 @@ combinations. The arguments are interpreted as follows:
*-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:** NOTES:
NONE NONE
**EXAMPLES:** EXAMPLES:
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 IP IP routing table:
routing table:
.. code-block:: shell .. code-block:: shell
@ -92,8 +91,8 @@ 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
@ -136,8 +135,8 @@ 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
@ -147,16 +146,16 @@ 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
@ -179,25 +178,23 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have
command included. 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
@ -212,14 +209,17 @@ The configuration structure for the ``netstats`` has the following prototype:
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
@ -227,22 +227,18 @@ ifconfig - configure a network 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
This command may be used to display information about the network interfaces in interfaces in the system or configure them.
the system or configure them.
**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:** NOTES:
Just like its counterpart on GNU/Linux and BSD systems, this command is Just like its counterpart on GNU/Linux and BSD systems, this command is
complicated. More example usages would be a welcome submission. complicated. More example usages would be a welcome submission.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``ifconfig``: The following is an example of how to use ``ifconfig``:
.. code-block:: shell .. code-block:: shell
@ -259,23 +255,21 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have
command included. 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
PROGRAMMING INFORMATION:
The ``ifconfig`` is implemented by a C language function which has the The ``ifconfig`` is implemented by a C language function which has the
following prototype: following prototype:
@ -286,30 +280,33 @@ following prototype:
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
This command is used to display and manipulate the routing table. When invoked invoked with no arguments, the current routing information is displayed.
with no arguments, the current routing information is displayed. When invoked When invoked with the subcommands ``add`` or ``del``, then additional
with the subcommands ``add`` or ``del``, then additional arguments must be arguments must be provided to describe the route.
provided to describe the route.
Command templates include the following: Command templates include the following:
@ -320,19 +317,16 @@ Command templates include the following:
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:** NOTES:
Just like its counterpart on GNU/Linux and BSD systems, this command is Just like its counterpart on GNU/Linux and BSD systems, this command is
complicated. More example usages would be a welcome submission. complicated. More example usages would be a welcome submission.
**EXAMPLES:** EXAMPLES:
The following is an example of how to use ``route`` to display, add, and
The following is an example of how to use ``route`` to display, add, and delete delete a new route:
a new route:
.. code-block:: shell .. code-block:: shell
@ -361,11 +355,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this
command included. command included.
@ -374,12 +367,11 @@ 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
@ -394,14 +386,17 @@ The configuration structure for the ``route`` has the following prototype:
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]
@ -413,20 +408,19 @@ 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
The ping utility uses the ICMP protocol's mandatory ECHO_REQUEST datagram to to elicit an ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST
elicit an ICMP ECHO_RESPONSE from a host or gateway. ECHO_REQUEST datagrams datagrams ("pings") have an IP and ICMP header, followed by a "struct
("pings") have an IP and ICMP header, followed by a "struct timeval" and then timeval" and then an arbitrary number of "pad" bytes used to fill out the
an arbitrary number of "pad" bytes used to fill out the packet. The options packet. The options are as follows:
are as follows:
*-A* *-A*
Audible. Output a bell (ASCII 0x07) character when no packet is received Audible. Output a bell (ASCII 0x07) character when no packet is
before the next packet is transmitted. To cater for round-trip times that received before the next packet is transmitted. To cater for
are longer than the interval between transmissions, further missing packets round-trip times that are longer than the interval between
cause a bell only if the maximum number of unreceived packets has transmissions, further missing packets cause a bell only if the maximum
increased. number of unreceived packets has increased.
*-a* *-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
@ -434,10 +428,10 @@ are as follows:
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.
@ -446,129 +440,131 @@ are as follows:
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.
@ -576,29 +572,29 @@ The ping utility exits with one of the following values:
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
When using ping for fault isolation, it should first be run on the local host, host, to verify that the local network interface is up and running. Then,
to verify that the local network interface is up and running. Then, hosts and hosts and gateways further and further away should be "pinged". Round-trip
gateways further and further away should be "pinged". Round-trip times and times and packet loss statistics are computed. If duplicate packets are
packet loss statistics are computed. If duplicate packets are received, they received, they are not included in the packet loss calculation, although
are not included in the packet loss calculation, although the round trip time the round trip time of these packets is used in calculating the round-trip
of these packets is used in calculating the round-trip time statistics. When time statistics. When the specified number of packets have been sent a
the specified number of packets have been sent a brief summary is displayed, brief summary is displayed, showing the number of packets sent and
showing the number of packets sent and received, and the minimum, mean, received, and the minimum, mean, maximum, and standard deviation of the
maximum, and standard deviation of the round-trip times. round-trip times.
This program is intended for use in network testing, measurement and This program is intended for use in network testing, measurement and
management. Because of the load it can impose on the network, it is unwise to management. Because of the load it can impose on the network, it is unwise
use ping during normal operations or from automated scripts. to use ping during normal operations or from automated scripts.
This command can fail if more than the FD_SET size number of file descriptors This command can fail if more than the FD_SET size number of file
are open. descriptors are open.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``oing`` to ping: The following is an example of how to use ``oing`` to ping:
.. code-block:: shell .. code-block:: shell
@ -620,11 +616,10 @@ 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
CONFIGURATION:
This command is included in the default shell command set. When building a This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this
command included. command included.
@ -633,10 +628,9 @@ 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
PROGRAMMING INFORMATION:
The ``ping`` is implemented by a C language function which has the following The ``ping`` is implemented by a C language function which has the following
prototype: prototype:

665
shell/rtems_specific_commands.rst
View File

File diff suppressed because it is too large Load Diff