rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 20:49:18 +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
available related to initialization and configuration.
.. raw:: latex
\clearpage
rtems_shell_init - Initialize the shell
---------------------------------------
.. index:: initialization
**CALLING SEQUENCE:**
.. index:: rtems_shell_init
CALLING SEQUENCE:
.. code-block:: c
rtems_status_code rtems_shell_init(
@ -316,35 +318,33 @@ rtems_shell_init - Initialize the shell
rtems_login_check login_check
);
**DIRECTIVE STATUS CODES:**
DIRECTIVE STATUS CODES:
``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
Shell attached to the specified ``devname``.
**NOTES:**
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.
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.
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.
.. raw:: latex
\clearpage
rtems_shell_login_check - Default login check handler
-----------------------------------------------------
.. index:: initialization
**CALLING SEQUENCE:**
.. index:: rtems_shell_login_check
CALLING SEQUENCE:
.. code:: c
bool rtems_shell_login_check(
@ -352,35 +352,32 @@ rtems_shell_login_check - Default login check handler
const char *passphrase
);
**DIRECTIVE STATUS CODES:**
DIRECTIVE STATUS CODES:
``true`` - login is allowed, and
``false`` - otherwise.
**DESCRIPTION:**
DESCRIPTION:
This function checks if the specified passphrase is valid for the specified
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,
this function:
- performs a filesystem change root operation to the directory of the 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
user,
- sets the real and effective UID of the current user environment to the UID of
the specified user,
- sets the real and effective UID of the current user environment to the
UID of the specified user,
- sets the real and effective GID of the current user environment to the GID of
the specified user, and
- sets the real and effective GID of the current user environment to the
GID of the specified user, and
- sets the supplementary group IDs of the current user environment to the
supplementary group IDs of the specified user.
In case the filesystem change root operation fails, then the environment setup
is aborted and ``false`` is returned.
In case the filesystem change root operation fails, then the environment
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::
:maxdepth: 3
:maxdepth: 4
:numbered:
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
command as well as providing an example usage.
.. raw:: latex
\clearpage
.. _mdump:
mdump - display contents of memory
----------------------------------
.. index:: mdump
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
mdump [address [length [size]]]
**DESCRIPTION:**
This command displays the contents of memory at the ``address`` and ``length``
in ``size`` byte units specified on the command line.
DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` in ``size`` byte units specified on the command line.
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
reported.
When ``length`` is not provided, it defaults to ``320`` which is twenty lines
of output with sixteen bytes of output per line.
When ``length`` is not provided, it defaults to ``320`` which is twenty
lines of output with sixteen bytes of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:**
EXIT STATUS:
This command always returns 0 to indicate success.
**NOTES:**
NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``mdump``:
.. 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..
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_COMMAND_MDUMP
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mdump
The ``mdump`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``mdump`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _wdump:
wdump - display contents of memory (word)
-----------------------------------------
.. index:: wdump
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
wdump [address [length]]
**DESCRIPTION:**
This command displays the contents of memory at the ``address`` and ``length``
in bytes specified on the command line.
DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` 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 of output with eight words of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:**
EXIT STATUS:
This command always returns 0 to indicate success.
**NOTES:**
NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``wdump``:
.. 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
0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...............
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP
.. index:: CONFIGURE_SHELL_COMMAND_WDUMP
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_wdump
The ``wdump`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``wdump`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _ldump:
ldump - display contents of memory (longword)
---------------------------------------------
.. index:: ldump
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
ldump [address [length]]
**DESCRIPTION:**
This command displays the contents of memory at the ``address`` and ``length``
in bytes specified on the command line.
DESCRIPTION:
This command displays the contents of memory at the ``address`` and
``length`` 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 of output with four longwords of output per line.
When ``address`` is not provided, it defaults to ``0x00000000``.
**EXIT STATUS:**
EXIT STATUS:
This command always returns 0 to indicate success.
**NOTES:**
NOTES:
Dumping memory from a non-existent address may result in an unrecoverable
program fault.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``ldump``:
.. code-block:: shell
@ -237,11 +230,10 @@ The following is an example of how to use ``ldump``:
0x02010000 020108D8 020108C0-020108AC 02010874 ...............t
0x02010010 020 0894 02010718-02010640 02010798 ...............
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP
.. index:: CONFIGURE_SHELL_COMMAND_LDUMP
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ldump
PROGRAMMING INFORMATION:
The ``ldump`` is implemented by a C language function which has the following
prototype:
@ -270,35 +261,34 @@ The configuration structure for the ``ldump`` has the following prototype:
extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
.. raw:: latex
\clearpage
.. _medit:
medit - modify contents of memory
---------------------------------
.. index:: medit
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
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``.
**EXIT STATUS:**
EXIT STATUS:
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
program fault.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``medit``:
.. 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 .........."...!.
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_COMMAND_MEDIT
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_medit
The ``medit`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``medit`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _mfill:
mfill - file memory with pattern
--------------------------------
.. index:: mfill
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
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``.
**EXIT STATUS:**
EXIT STATUS:
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
fault. Similarly overwriting interrupt vector tables, code space or critical
data areas can be fatal as shown in the example.
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.
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
@ -391,11 +379,10 @@ detect the pattern has been corrupted and generates a fatal error.
stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
Damaged pattern begins at 0x023D89A8 and is 16 bytes long
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL
.. index:: CONFIGURE_SHELL_COMMAND_MFILL
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mfill
The ``mfill`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``mfill`` is implemented by a C language function which has the
following prototype:
.. code-block:: c
@ -425,33 +411,32 @@ following prototype:
extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
.. raw:: latex
\clearpage
.. _mmove:
mmove - move contents of memory
-------------------------------
.. index:: mmove
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
mmove dst src length
**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.
**EXIT STATUS:**
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.
EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
**NOTES:**
NOTES:
NONE
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``mmove``:
.. code-block:: shell
@ -464,11 +449,10 @@ The following is an example of how to use ``mmove``:
SHLL [/] $ mdump 0x023d99a0 16
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_COMMAND_MMOVE
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_mmove
The ``mmove`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``mmove`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _malloc:
malloc - obtain information on C program heap
---------------------------------------------
.. index:: malloc
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
malloc [walk]
**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:
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:
- Number of free blocks
@ -549,19 +534,16 @@ the command. This includes the following information:
- 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.
**EXIT STATUS:**
When the subcommand ``walk`` is specified, then a heap walk will be
performed and information about each block is printed out.
EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
**NOTES:**
NOTES:
NONE
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use the ``malloc`` command.
.. 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 0x0FFFBFDC: size 4028711480, prev_size 266157192
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC
.. index:: CONFIGURE_SHELL_COMMAND_MALLOC
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_malloc
The ``malloc`` is implemented by a C language function
which has the following prototype:
PROGRAMMING INFORMATION:
The ``malloc`` is implemented by a C language function which has the
following prototype:
.. 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
command as well as providing an example usage.
.. raw:: latex
\clearpage
.. _netstats:
netstats - obtain network statistics
------------------------------------
.. index:: netstats
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
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:
information displayed can be specified using command line arguments in
various combinations. The arguments are interpreted as follows:
*-A*
print All statistics
@ -69,18 +71,15 @@ combinations. The arguments are interpreted as follows:
*-t*
print TCP Statistics
**EXIT STATUS:**
EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
**NOTES:**
NOTES:
NONE
**EXAMPLES:**
The following is an example of using the ``netstats`` command to print the IP
routing table:
EXAMPLES:
The following is an example of using the ``netstats`` command to print the
IP routing table:
.. 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.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
statistics:
The following is an example of using the ``netstats`` command to print the
MBUF statistics:
.. code-block:: shell
@ -136,8 +135,8 @@ print IP statistics:
datagrams delivered to upper level 881
total ip packets generated here 871
The following is an example of using the ``netstats`` command to print the ICMP
statistics:
The following is an example of using the ``netstats`` command to print the
ICMP statistics:
.. code-block:: shell
@ -147,16 +146,16 @@ statistics:
number of responses 843
Type 8 received 843
The following is an example of using the ``netstats`` command to print the UDP
statistics:
The following is an example of using the ``netstats`` command to print the
UDP statistics:
.. code-block:: shell
[/] $ netstats -u
************ UDP Statistics ************
The following is an example of using the ``netstats`` command to print the TCP
statistics:
The following is an example of using the ``netstats`` command to print the
TCP statistics:
.. code-block:: shell
@ -179,25 +178,23 @@ statistics:
times hdr predict ok for acks 27
times hdr predict ok for data pkts 10
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS
.. index:: CONFIGURE_SHELL_COMMAND_NETSTATS
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this
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
``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_netstats
The ``netstats`` is implemented by a C language function
which has the following prototype:
PROGRAMMING INFORMATION:
The ``netstats`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _ifconfig:
ifconfig - configure a network interface
----------------------------------------
.. index:: ifconfig
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
ifconfig
@ -227,22 +227,18 @@ ifconfig - configure a network interface
ifconfig interface \[up|down]
ifconfig interface \[netmask|pointtopoint|broadcast] IP
**DESCRIPTION:**
This command may be used to display information about the network interfaces in
the system or configure them.
**EXIT STATUS:**
DESCRIPTION:
This command may be used to display information about the network
interfaces in the system or configure them.
EXIT STATUS:
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
complicated. More example usages would be a welcome submission.
**EXAMPLES:**
EXAMPLES:
The following is an example of how to use ``ifconfig``:
.. 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
Retransmit Limit:0 Underrun:0 Misaligned:0
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
.. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this
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
``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ifconfig
PROGRAMMING INFORMATION:
The ``ifconfig`` is implemented by a C language function which has the
following prototype:
@ -286,30 +280,33 @@ following prototype:
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
extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
.. raw:: latex
\clearpage
.. _route:
route - show or manipulate the ip routing table
-----------------------------------------------
.. index:: route
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
route [subcommand] [args]
**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.
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.
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``
**EXIT STATUS:**
EXIT STATUS:
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
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:
EXAMPLES:
The following is an example of how to use ``route`` to display, add, and
delete a new route:
.. 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.151 00:1C:23:B2:0F:BB UHL 2 117 1399 eth1
**CONFIGURATION:**
.. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE
.. index:: CONFIGURE_SHELL_COMMAND_ROUTE
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_route
The ``route`` is implemented by a C language function which has the following
prototype:
PROGRAMMING INFORMATION:
The ``route`` is implemented by a C language function which has the
following prototype:
.. 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;
.. raw:: latex
\clearpage
.. _ping:
ping - ping a host or IP address
--------------------------------
.. index:: ping
**SYNOPSYS:**
SYNOPSYS:
.. code-block:: shell
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]
[-z tos] mcast-group
**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:
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:
*-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.
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
@ -434,10 +428,10 @@ are as follows:
present.
*-c count*
Stop after sending (and receiving) count ECHO_RESPONSE packets. If this
option is not specified, ping will operate until interrupted. If this
option is specified in conjunction with ping sweeps, each sweep will
consist of count packets.
Stop after sending (and receiving) count ECHO_RESPONSE packets. If
this option is not specified, ping will operate until interrupted. If
this option is specified in conjunction with ping sweeps, each sweep
will consist of count packets.
*-D*
Set the Don't Fragment bit.
@ -446,129 +440,131 @@ are as follows:
Set the SO_DEBUG option on the socket being used.
*-f*
Flood ping. Outputs packets as fast as they come back or one hundred times
per second, whichever is more. For every ECHO_REQUEST sent a period "." is
printed, while for every ECHO_REPLY received a backspace is printed. This
provides a rapid display of how many packets are being dropped. Only the
super-user may use this option. This can be very hard on a network and
should be used with caution.
Flood ping. Outputs packets as fast as they come back or one hundred
times per second, whichever is more. For every ECHO_REQUEST sent a
period "." is printed, while for every ECHO_REPLY received a backspace
is printed. This provides a rapid display of how many packets are
being dropped. Only the super-user may use this option. This can be
very hard on a network and should be used with caution.
*-G sweepmaxsize*
Specify the maximum size of ICMP payload when sending sweeping pings. This
option is required for ping sweeps.
Specify the maximum size of ICMP payload when sending sweeping pings.
This option is required for ping sweeps.
*-g sweepminsize*
Specify the size of ICMP payload to start with when sending sweeping pings.
The default value is 0.
Specify the size of ICMP payload to start with when sending sweeping
pings. The default value is 0.
*-h sweepincrsize*
Specify the number of bytes to increment the size of ICMP payload after
each sweep when sending sweeping pings. The default value is 1.
*-I iface*
Source multicast packets with the given interface address. This flag only
applies if the ping destination is a multicast address.
Source multicast packets with the given interface address. This flag
only applies if the ping destination is a multicast address.
*-i wait*
Wait wait seconds between sending each packet. The default is to wait for
one second between each packet. The wait time may be fractional, but only
the super-user may specify values less than 1 second. This option is
incompatible with the -f option.
Wait wait seconds between sending each packet. The default is to wait
for one second between each packet. The wait time may be fractional,
but only the super-user may specify values less than 1 second. This
option is incompatible with the -f option.
*-L*
Suppress loopback of multicast packets. This flag only applies if the ping
destination is a multicast address.
Suppress loopback of multicast packets. This flag only applies if the
ping destination is a multicast address.
*-l preload*
If preload is specified, ping sends that many packets as fast as possible
before falling into its normal mode of behavior. Only the super-user may
use this option.
If preload is specified, ping sends that many packets as fast as
possible before falling into its normal mode of behavior. Only the
super-user may use this option.
*-M mask | time*
Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO. For mask, print the
netmask of the remote machine. Set the net.inet.icmp.maskrepl MIB variable
to enable ICMP_MASKREPLY. For time, print the origination, reception and
transmission timestamps.
Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO. For mask, print
the netmask of the remote machine. Set the net.inet.icmp.maskrepl MIB
variable to enable ICMP_MASKREPLY. For time, print the origination,
reception and transmission timestamps.
*-m ttl*
Set the IP Time To Live for outgoing packets. If not specified, the kernel
uses the value of the net.inet.ip.ttl MIB variable.
Set the IP Time To Live for outgoing packets. If not specified, the
kernel uses the value of the net.inet.ip.ttl MIB variable.
*-n*
Numeric output only. No attempt will be made to lookup symbolic names for
host addresses.
Numeric output only. No attempt will be made to lookup symbolic names
for host addresses.
*-o*
Exit successfully after receiving one reply packet.
*-p pattern*
You may specify up to 16 "pad" bytes to fill out the packet you send. This
is useful for diagnosing data-dependent problems in a network. For
example, "-p ff" will cause the sent packet to be filled with all ones.
You may specify up to 16 "pad" bytes to fill out the packet you send.
This is useful for diagnosing data-dependent problems in a network.
For example, "-p ff" will cause the sent packet to be filled with all
ones.
*-Q*
Somewhat quiet output. Don't display ICMP error messages that are in
response to our query messages. Originally, the -v flag was required to
display such errors, but -v displays all ICMP error messages. On a busy
machine, this output can be overbear- ing. Without the -Q flag, ping
prints out any ICMP error mes- sages caused by its own ECHO_REQUEST
messages.
response to our query messages. Originally, the -v flag was required
to display such errors, but -v displays all ICMP error messages. On a
busy machine, this output can be overbear- ing. Without the -Q flag,
ping prints out any ICMP error mes- sages caused by its own
ECHO_REQUEST messages.
*-q*
Quiet output. Nothing is displayed except the summary lines at startup
time and when finished.
*-R*
Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST packet
and displays the route buffer on returned packets. Note that the IP header
is only large enough for nine such routes; the traceroute(8) command is
usually better at determining the route packets take to a particular
destination. If more routes come back than should, such as due to an
illegal spoofed packet, ping will print the route list and then truncate it
at the correct spot. Many hosts ignore or discard the RECORD_ROUTE option.
Record route. Includes the RECORD_ROUTE option in the ECHO_REQUEST
packet and displays the route buffer on returned packets. Note that
the IP header is only large enough for nine such routes; the
traceroute(8) command is usually better at determining the route
packets take to a particular destination. If more routes come back
than should, such as due to an illegal spoofed packet, ping will print
the route list and then truncate it at the correct spot. Many hosts
ignore or discard the RECORD_ROUTE option.
*-r*
Bypass the normal routing tables and send directly to a host on an attached
network. If the host is not on a directly-attached network, an error is
returned. This option can be used to ping a local host through an
interface that has no route through it (e.g., after the interface was
dropped).
Bypass the normal routing tables and send directly to a host on an
attached network. If the host is not on a directly-attached network,
an error is returned. This option can be used to ping a local host
through an interface that has no route through it (e.g., after the
interface was dropped).
*-S src_addr*
Use the following IP address as the source address in outgoing packets. On
hosts with more than one IP address, this option can be used to force the
source address to be something other than the IP address of the interface
the probe packet is sent on. If the IP address is not one of this
machine's interface addresses, an error is returned and nothing is sent.
Use the following IP address as the source address in outgoing packets.
On hosts with more than one IP address, this option can be used to
force the source address to be something other than the IP address of
the interface the probe packet is sent on. If the IP address is not
one of this machine's interface addresses, an error is returned and
nothing is sent.
*-s packetsize*
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
header data. Only the super-user may specify val- ues more than default.
This option cannot be used with ping sweeps.
translates into 64 ICMP data bytes when combined with the 8 bytes of
ICMP header data. Only the super-user may specify val- ues more than
default. This option cannot be used with ping sweeps.
*-T ttl*
Set the IP Time To Live for multicasted packets. This flag only applies if
the ping destination is a multicast address.
Set the IP Time To Live for multicasted packets. This flag only
applies if the ping destination is a multicast address.
*-t timeout*
Specify a timeout, in seconds, before ping exits regardless of how many
packets have been received.
*-v*
Verbose output. ICMP packets other than ECHO_RESPONSE that are received
are listed.
Verbose output. ICMP packets other than ECHO_RESPONSE that are
received are listed.
*-W waittime*
Time in milliseconds to wait for a reply for each packet sent. If a reply
arrives later, the packet is not printed as replied, but considered as
replied when calculating statistics.
Time in milliseconds to wait for a reply for each packet sent. If a
reply arrives later, the packet is not printed as replied, but
considered as replied when calculating statistics.
*-z tos*
Use the specified type of service.
**EXIT STATUS:**
EXIT STATUS:
The ping utility exits with one of the following values:
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
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:**
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.
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.
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
use ping during normal operations or from automated scripts.
management. Because of the load it can impose on the network, it is unwise
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
are open.
**EXAMPLES:**
This command can fail if more than the FD_SET size number of file
descriptors are open.
EXAMPLES:
The following is an example of how to use ``oing`` to ping:
.. 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
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_COMMAND_PING
CONFIGURATION:
This command is included in the default shell command set. When building a
custom command set, define ``CONFIGURE_SHELL_COMMAND_PING`` to have this
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
configured.
**PROGRAMMING INFORMATION:**
.. index:: rtems_shell_rtems_main_ping
PROGRAMMING INFORMATION:
The ``ping`` is implemented by a C language function which has the following
prototype:

665
shell/rtems_specific_commands.rst
View File

File diff suppressed because it is too large Load Diff