From bf61a8b14e57ef56e8f5e190e9bdd0ba5db16a6f Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Tue, 8 Nov 2016 21:33:20 +1100 Subject: shell: Update commands to use descriptions. --- shell/configuration_and_init.rst | 119 +- shell/file_and_directory.rst | 3677 ++++++++++++++++++------------------- shell/general_commands.rst | 1466 +++++++-------- shell/index.rst | 2 +- shell/memory_commands.rst | 756 ++++---- shell/network_commands.rst | 1022 +++++------ shell/rtems_specific_commands.rst | 1749 +++++++++--------- 7 files changed, 4303 insertions(+), 4488 deletions(-) diff --git a/shell/configuration_and_init.rst b/shell/configuration_and_init.rst index cb60ce7..4895fdb 100644 --- a/shell/configuration_and_init.rst +++ b/shell/configuration_and_init.rst @@ -296,91 +296,88 @@ 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 -.. code-block:: c - - rtems_status_code rtems_shell_init( - const char *task_name, - size_t task_stacksize, - rtems_task_priority task_priority, - const char *devname, - bool forever, - bool wait, - rtems_login_check login_check - ); - -**DIRECTIVE STATUS CODES:** - -``RTEMS_SUCCESSFUL`` - Shell task spawned successfully +CALLING SEQUENCE: + .. code-block:: c + + rtems_status_code rtems_shell_init( + const char *task_name, + size_t task_stacksize, + rtems_task_priority task_priority, + const char *devname, + bool forever, + bool wait, + rtems_login_check login_check + ); -others - to indicate a failure condition +DIRECTIVE STATUS CODES: + ``RTEMS_SUCCESSFUL`` - Shell task spawned successfully + *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``. -This service creates a task with the specified characteristics to run the RTEMS -Shell attached to the specified ``devname``. +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. -**NOTES:** + There is one POSIX key necessary for all shell instances together and one + POSIX key value pair per instance. You should make sure that your RTEMS + configuration accounts for these resources. -This method invokes the ``rtems_task_create`` and ``rtems_task_start`` -directives and as such may return any status code that those directives may -return. +.. raw:: latex -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. + \clearpage rtems_shell_login_check - Default login check handler ----------------------------------------------------- .. index:: initialization - -**CALLING SEQUENCE:** - .. index:: rtems_shell_login_check -.. code:: c - - bool rtems_shell_login_check( - const char *user, - const char *passphrase - ); - -**DIRECTIVE STATUS CODES:** - -``true`` - login is allowed, and -``false`` - otherwise. +CALLING SEQUENCE: + .. code:: c -**DESCRIPTION:** + bool rtems_shell_login_check( + const char *user, + const char *passphrase + ); -This function checks if the specified passphrase is valid for the specified -user. +DIRECTIVE STATUS CODES: + ``true`` - login is allowed, and + ``false`` - otherwise. -**NOTES:** +DESCRIPTION: + This function checks if the specified passphrase is valid for the specified + user. -As a side-effect if the specified passphrase is valid for the specified user, -this function: +NOTES: + 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, + - 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. + - 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. diff --git a/shell/file_and_directory.rst b/shell/file_and_directory.rst index 6ab0eb6..30db07d 100644 --- a/shell/file_and_directory.rst +++ b/shell/file_and_directory.rst @@ -73,72 +73,73 @@ This section details the File and Directory 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 + .. _blksync: blksync - sync the block driver ------------------------------- .. index:: blksync -**SYNOPSYS:** - -.. code-block:: shell - - blksync driver - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command issues a block driver sync call to the driver. The driver is a -path to a device node. The sync call will flush all pending writes in the cache -to the media and block until the writes have completed. + blksync driver -**EXIT STATUS:** +DESCRIPTION: + This command issues a block driver sync call to the driver. The driver is a + path to a device node. The sync call will flush all pending writes in the + cache to the media and block until the writes have completed. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + None. -None. +EXAMPLES: + The following is an example of how to use ``blksync``: -**EXAMPLES:** + .. code-block:: c -The following is an example of how to use ``blksync``: - -.. code-block:: c - - blksync /dev/hda1 - -**CONFIGURATION:** + blksync /dev/hda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_BLKSYNC .. index:: CONFIGURE_SHELL_COMMAND_BLKSYNC -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_BLKSYNC`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_BLKSYNC`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_BLKSYNC`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_BLKSYNC`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_blksync -The ``blksync`` is implemented by a C language function -which has the following prototype: +PROGRAMMING INFORMATION: + The ``blksync`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_blksync( + int argc, + char **argv + ); - int rtems_shell_rtems_main_blksync( - int argc, - char **argv - ); + The configuration structure for the ``blksync`` has the following prototype: -The configuration structure for the ``blksync`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command; - extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command; +.. raw:: latex + + \clearpage .. _cat: @@ -146,67 +147,64 @@ cat - display file contents --------------------------- .. index:: cat -**SYNOPSYS:** - -.. code-block:: shell - - cat file1 [file2 .. fileN] - -**DESCRIPTION:** - -This command displays the contents of the specified files. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + cat file1 [file2 .. fileN] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + This command displays the contents of the specified files. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -It is possible to read the input from a device file using ``cat``. +NOTES: + It is possible to read the input from a device file using ``cat``. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``cat``: -The following is an example of how to use ``cat``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] # cat /etc/passwd - root:*:0:0:root::/:/bin/sh - rtems:*:1:1:RTEMS Application::/:/bin/sh - tty:!:2:2:tty owner::/:/bin/false - -**CONFIGURATION:** + SHLL [/] # cat /etc/passwd + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false .. index:: CONFIGURE_SHELL_NO_COMMAND_CAT .. index:: CONFIGURE_SHELL_COMMAND_CAT -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CAT`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CAT`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CAT`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CAT`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_cat -The ``cat`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``cat`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_cat( + int argc, + char **argv + ); - int rtems_shell_rtems_main_cat( - int argc, - char **argv - ); + The configuration structure for the ``cat`` has the following prototype: -The configuration structure for the ``cat`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CAT_Command; - extern rtems_shell_cmd_t rtems_shell_CAT_Command; +.. raw:: latex + + \clearpage .. _cd: @@ -214,75 +212,73 @@ cd - alias for chdir -------------------- .. index:: cd -**SYNOPSYS:** - -.. code-block:: shell - - cd directory - -**DESCRIPTION:** - -This command is an alias or alternate name for the ``chdir``. See `ls - list -files in the directory` for more information. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + cd directory -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + This command is an alias or alternate name for the ``chdir``. See `ls - + list files in the directory` for more information. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -None. +NOTES: + None. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``cd``: -The following is an example of how to use ``cd``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ cd etc - SHLL [/etc] $ cd / - SHLL [/] $ cd /etc - SHLL [/etc] $ pwd - /etc - SHLL [/etc] $ cd / - SHLL [/] $ pwd - / - SHLL [/] $ cd etc - SHLL [/etc] $ cd .. - SHLL [/] $ pwd - / - -**CONFIGURATION:** + SHLL [/] $ cd etc + SHLL [/etc] $ cd / + SHLL [/] $ cd /etc + SHLL [/etc] $ pwd + /etc + SHLL [/etc] $ cd / + SHLL [/] $ pwd + / + SHLL [/] $ cd etc + SHLL [/etc] $ cd .. + SHLL [/] $ pwd + / .. index:: CONFIGURE_SHELL_NO_COMMAND_CD .. index:: CONFIGURE_SHELL_COMMAND_CD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CD`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CD`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CD`` when all shell commands have been configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CD`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_cd -The ``cd`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``cd`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_cd( + int argc, + char **argv + ); - int rtems_shell_rtems_main_cd( - int argc, - char **argv - ); + The configuration structure for the ``cd`` has the following prototype: -The configuration structure for the ``cd`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CD_Command; - extern rtems_shell_cmd_t rtems_shell_CD_Command; +.. raw:: latex + + \clearpage .. _chdir: @@ -290,70 +286,67 @@ chdir - change the current directory ------------------------------------ .. index:: chdir -**SYNOPSYS:** - -.. code-block:: shell - - chdir [dir] - -**DESCRIPTION:** - -This command is used to change the current working directory to the specified -directory. If no arguments are given, the current working directory will be -changed to ``/``. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + chdir [dir] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + This command is used to change the current working directory to the + specified directory. If no arguments are given, the current working + directory will be changed to ``/``. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -None. +NOTES: + None. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``chdir``: -The following is an example of how to use ``chdir``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ pwd - / - SHLL [/] $ chdir etc - SHLL [/etc] $ pwd - /etc - -**CONFIGURATION:** + SHLL [/] $ pwd + / + SHLL [/] $ chdir etc + SHLL [/etc] $ pwd + /etc .. index:: CONFIGURE_SHELL_NO_COMMAND_CHDIR .. index:: CONFIGURE_SHELL_COMMAND_CHDIR -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CHDIR`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CHDIR`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CHDIR`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CHDIR`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_chdir -The ``chdir`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``chdir`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_chdir( + int argc, + char **argv + ); - int rtems_shell_rtems_main_chdir( - int argc, - char **argv - ); + The configuration structure for the ``chdir`` has the following prototype: -The configuration structure for the ``chdir`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CHDIR_Command; - extern rtems_shell_cmd_t rtems_shell_CHDIR_Command; +.. raw:: latex + + \clearpage .. _chmod: @@ -361,94 +354,92 @@ chmod - change permissions of a file ------------------------------------ .. index:: chmod -**SYNOPSYS:** - -.. code-block:: shell - - chmod permissions file1 [file2...] - -**DESCRIPTION:** - -This command changes the permissions on the files specified to the indicated -``permissions``. The permission values are POSIX based with owner, group, and -world having individual read, write, and executive permission bits. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -The ``chmod`` command only takes numeric representations of -the permissions. - -**EXAMPLES:** - -The following is an example of how to use ``chmod``: - -.. code-block:: shell - - SHLL [/] # cd etc - SHLL [/etc] # ls - -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:00 group - -rw-r--r-- 1 root root 30 Jan 01 00:00 issue - -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - SHLL [/etc] # chmod 0777 passwd - SHLL [/etc] # ls - -rwxrwxrwx 1 root root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:00 group - -rw-r--r-- 1 root root 30 Jan 01 00:00 issue - -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - SHLL [/etc] # chmod 0322 passwd - SHLL [/etc] # ls - --wx-w--w- 1 nouser root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 nouser root 42 Jan 01 00:00 group - -rw-r--r-- 1 nouser root 30 Jan 01 00:00 issue - -rw-r--r-- 1 nouser root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - SHLL [/etc] # chmod 0644 passwd - SHLL [/etc] # ls - -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:00 group - -rw-r--r-- 1 root root 30 Jan 01 00:00 issue - -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + chmod permissions file1 [file2...] + +DESCRIPTION: + This command changes the permissions on the files specified to the + indicated ``permissions``. The permission values are POSIX based with + owner, group, and world having individual read, write, and executive + permission bits. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + The ``chmod`` command only takes numeric representations of the + permissions. + +EXAMPLES: + The following is an example of how to use ``chmod``: + + .. code-block:: shell + + SHLL [/] # cd etc + SHLL [/etc] # ls + -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:00 group + -rw-r--r-- 1 root root 30 Jan 01 00:00 issue + -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied + SHLL [/etc] # chmod 0777 passwd + SHLL [/etc] # ls + -rwxrwxrwx 1 root root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:00 group + -rw-r--r-- 1 root root 30 Jan 01 00:00 issue + -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied + SHLL [/etc] # chmod 0322 passwd + SHLL [/etc] # ls + --wx-w--w- 1 nouser root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 nouser root 42 Jan 01 00:00 group + -rw-r--r-- 1 nouser root 30 Jan 01 00:00 issue + -rw-r--r-- 1 nouser root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied + SHLL [/etc] # chmod 0644 passwd + SHLL [/etc] # ls + -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:00 group + -rw-r--r-- 1 root root 30 Jan 01 00:00 issue + -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied .. index:: CONFIGURE_SHELL_NO_COMMAND_CHMOD .. index:: CONFIGURE_SHELL_COMMAND_CHMOD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CHMOD`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CHMOD`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CHMOD`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CHMOD`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_chmod -The ``chmod`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``chmod`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_chmod( - int argc, - char **argv - ); + int rtems_shell_rtems_main_chmod( + int argc, + char **argv + ); -The configuration structure for the ``chmod`` has the following prototype: + The configuration structure for the ``chmod`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_CHMOD_Command; + extern rtems_shell_cmd_t rtems_shell_CHMOD_Command; + +.. raw:: latex + + \clearpage .. _chroot: @@ -456,76 +447,73 @@ chroot - change the root directory ---------------------------------- .. index:: chroot -**SYNOPSYS:** - -.. code-block:: shell - - chroot [dir] +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + chroot [dir] -This command changes the root directory to ``dir`` for subsequent commands. +DESCRIPTION: + This command changes the root directory to ``dir`` for subsequent commands. -**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. + The destination directory ``dir`` must exist. -The destination directory ``dir`` must exist. +NOTES: + None. -**NOTES:** +EXAMPLES: + The following is an example of how to use ``chroot`` and the impact it has + on the environment for subsequent command invocations: -None. + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``chroot`` and the impact it has on -the environment for subsequent command invocations: - -.. code-block:: shell - - SHLL [/] $ cat passwd - cat: passwd: No such file or directory - SHLL [/] $ chroot etc - SHLL [/] $ cat passwd - root:*:0:0:root::/:/bin/sh - rtems:*:1:1:RTEMS Application::/:/bin/sh - tty:!:2:2:tty owner::/:/bin/false - SHLL [/] $ cat /etc/passwd - cat: /etc/passwd: No such file or directory - -**CONFIGURATION:** + SHLL [/] $ cat passwd + cat: passwd: No such file or directory + SHLL [/] $ chroot etc + SHLL [/] $ cat passwd + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false + SHLL [/] $ cat /etc/passwd + cat: /etc/passwd: No such file or directory .. index:: CONFIGURE_SHELL_NO_COMMAND_CHROOT .. index:: CONFIGURE_SHELL_COMMAND_CHROOT -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CHROOT`` to have this -command included. Additional to that you have to add one POSIX key value pair -for each thread where you want to use the command. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CHROOT`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CHROOT`` to have this + command included. Additional to that you have to add one POSIX key value + pair for each thread where you want to use the command. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CHROOT`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_chroot -The ``chroot`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``chroot`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_chroot( - int argc, - char **argv - ); + int rtems_shell_rtems_main_chroot( + int argc, + char **argv + ); -The configuration structure for the ``chroot`` has the following prototype: + The configuration structure for the ``chroot`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_CHROOT_Command; + extern rtems_shell_cmd_t rtems_shell_CHROOT_Command; + +.. raw:: latex + + \clearpage .. _cp: @@ -533,178 +521,182 @@ cp - copy files --------------- .. index:: cp -**SYNOPSYS:** - -.. code-block:: shell - - cp [-R [-H | -L | -P]] [-f | -i] [-pv] src target - cp [-R [-H | -L] ] [-f | -i] [-NpPv] source_file ... target_directory +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + cp [-R [-H | -L | -P]] [-f | -i] [-pv] src target + cp [-R [-H | -L] ] [-f | -i] [-NpPv] source_file ... target_directory -In the first synopsis form, the cp utility copies the contents of the -source_file to the target_file. In the second synopsis form, the contents of -each named source_file is copied to the destination target_directory. The names -of the files themselves are not changed. If cp detects an attempt to copy a -file to itself, the copy will fail. - -The following options are available: +DESCRIPTION: + In the first synopsis form, the cp utility copies the contents of the + source_file to the target_file. In the second synopsis form, the contents + of each named source_file is copied to the destination + target_directory. The names of the files themselves are not changed. If cp + detects an attempt to copy a file to itself, the copy will fail. -*-f* - For each existing destination pathname, attempt to overwrite it. If permissions - do not allow copy to succeed, remove it and create a new file, without - prompting for confirmation. (The -i option is ignored if the -f option is - specified.) + The following options are available: -*-H* - If the -R option is specified, symbolic links on the command line are followed. - (Symbolic links encountered in the tree traversal are not followed.) - -*-i* - Causes cp to write a prompt to the standard error output before copying a file - that would overwrite an existing file. If the response from the standard input - begins with the character 'y', the file copy is attempted. - -*-L* - If the -R option is specified, all symbolic links are followed. - -*-N* - When used with -p, do not copy file flags. - -*-P* - No symbolic links are followed. - -*-p* - Causes cp to preserve in the copy as many of the modification time, access - time, file flags, file mode, user ID, and group ID as allowed by permissions. - If the user ID and group ID cannot be preserved, no error message is displayed - and the exit value is not altered. - If the source file has its set user ID bit on and the user ID cannot be - preserved, the set user ID bit is not preserved in the copy's permissions. If - the source file has its set group ID bit on and the group ID cannot be - preserved, the set group ID bit is not preserved in the copy's permissions. If - the source file has both its set user ID and set group ID bits on, and either - the user ID or group ID cannot be preserved, neither the set user ID or set - group ID bits are preserved in the copy's permissions. - -*-R* - If source_file designates a directory, cp copies the directory and the entire - subtree connected at that point. This option also causes symbolic links to be - copied, rather than indirected through, and for cp to create special files - rather than copying them as normal files. Created directories have the same - mode as the corresponding source directory, unmodified by the process's umask. - -*-v* - Cause cp to be verbose, showing files as they are copied. - -For each destination file that already exists, its contents are overwritten if -permissions allow, but its mode, user ID, and group ID are unchanged. - -In the second synopsis form, target_directory must exist unless there is only -one named source_file which is a directory and the -R flag is specified. - -If the destination file does not exist, the mode of the source file is used as -modified by the file mode creation mask (umask, see csh(1)). If the source file -has its set user ID bit on, that bit is removed unless both the source file and -the destination file are owned by the same user. If the source file has its set -group ID bit on, that bit is removed unless both the source file and the -destination file are in the same group and the user is a member of that group. -If both the set user ID and set group ID bits are set, all of the above -conditions must be fulfilled or both bits are removed. - -Appropriate permissions are required for file creation or overwriting. - -Symbolic links are always followed unless the -R flag is set, in which case -symbolic links are not followed, by default. The -H or -L flags (in conjunction -with the -R flag), as well as the -P flag cause symbolic links to be followed -as described above. The -H and -L options are ignored unless the -R option is -specified. In addition, these options override eachsubhedading other and the -command's actions are determined by the last one specified. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``cp`` to copy a file to a new name -in the current directory: - -.. code-block:: shell - - SHLL [/] # cat joel - cat: joel: No such file or directory - SHLL [/] # cp etc/passwd joel - SHLL [/] # cat joel - root:*:0:0:root::/:/bin/sh - rtems:*:1:1:RTEMS Application::/:/bin/sh - tty:!:2:2:tty owner::/:/bin/false - SHLL [/] # ls - drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ - drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ - -rw-r--r-- 1 root root 102 Jan 01 00:00 joel - 3 files 1710 bytes occupied - -The following is an example of how to use ``cp`` to -copy one or more files to a destination directory and -use the same ``basename`` in the destination directory: - -.. code-block:: shell - - SHLL [/] # mkdir tmp - SHLL [/] # ls tmp - 0 files 0 bytes occupied - SHLL [/] # cp /etc/passwd tmp - SHLL [/] # ls /tmp - -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd - 1 files 102 bytes occupied - SHLL [/] # cp /etc/passwd /etc/group /tmp - SHLL [/] # ls /tmp - -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:01 group - 2 files 144 bytes occupied - SHLL [/] # - -**CONFIGURATION:** + *-f* + For each existing destination pathname, attempt to overwrite it. If + permissions do not allow copy to succeed, remove it and create a new + file, without prompting for confirmation. (The -i option is ignored if + the -f option is specified.) + + *-H* + If the -R option is specified, symbolic links on the command line are + followed. (Symbolic links encountered in the tree traversal are not + followed.) + + *-i* + Causes cp to write a prompt to the standard error output before copying + a file that would overwrite an existing file. If the response from the + standard input begins with the character 'y', the file copy is + attempted. + + *-L* + If the -R option is specified, all symbolic links are followed. + + *-N* + When used with -p, do not copy file flags. + + *-P* + No symbolic links are followed. + + *-p* + Causes cp to preserve in the copy as many of the modification time, + access time, file flags, file mode, user ID, and group ID as allowed by + permissions. If the user ID and group ID cannot be preserved, no error + message is displayed and the exit value is not altered. If the source + file has its set user ID bit on and the user ID cannot be preserved, + the set user ID bit is not preserved in the copy's permissions. If the + source file has its set group ID bit on and the group ID cannot be + preserved, the set group ID bit is not preserved in the copy's + permissions. If the source file has both its set user ID and set group + ID bits on, and either the user ID or group ID cannot be preserved, + neither the set user ID or set group ID bits are preserved in the + copy's permissions. + + *-R* + If source_file designates a directory, cp copies the directory and the + entire subtree connected at that point. This option also causes + symbolic links to be copied, rather than indirected through, and for cp + to create special files rather than copying them as normal + files. Created directories have the same mode as the corresponding + source directory, unmodified by the process's umask. + + *-v* + Cause cp to be verbose, showing files as they are copied. + + For each destination file that already exists, its contents are overwritten + if permissions allow, but its mode, user ID, and group ID are unchanged. + + In the second synopsis form, target_directory must exist unless there is + only one named source_file which is a directory and the -R flag is + specified. + + If the destination file does not exist, the mode of the source file is used + as modified by the file mode creation mask (umask, see csh(1)). If the + source file has its set user ID bit on, that bit is removed unless both the + source file and the destination file are owned by the same user. If the + source file has its set group ID bit on, that bit is removed unless both + the source file and the destination file are in the same group and the user + is a member of that group. If both the set user ID and set group ID bits + are set, all of the above conditions must be fulfilled or both bits are + removed. + + Appropriate permissions are required for file creation or overwriting. + + Symbolic links are always followed unless the -R flag is set, in which case + symbolic links are not followed, by default. The -H or -L flags (in + conjunction with the -R flag), as well as the -P flag cause symbolic links + to be followed as described above. The -H and -L options are ignored unless + the -R option is specified. In addition, these options override + eachsubhedading other and the command's actions are determined by the last + one specified. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + NONE + +EXAMPLES: + The following is an example of how to use ``cp`` to copy a file to a new + name in the current directory: + + .. code-block:: shell + + SHLL [/] # cat joel + cat: joel: No such file or directory + SHLL [/] # cp etc/passwd joel + SHLL [/] # cat joel + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false + SHLL [/] # ls + drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ + drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ + -rw-r--r-- 1 root root 102 Jan 01 00:00 joel + 3 files 1710 bytes occupied + + The following is an example of how to use ``cp`` to copy one or more files + to a destination directory and use the same ``basename`` in the destination + directory: + + .. code-block:: shell + + SHLL [/] # mkdir tmp + SHLL [/] # ls tmp + 0 files 0 bytes occupied + SHLL [/] # cp /etc/passwd tmp + SHLL [/] # ls /tmp + -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd + 1 files 102 bytes occupied + SHLL [/] # cp /etc/passwd /etc/group /tmp + SHLL [/] # ls /tmp + -rw-r--r-- 1 root root 102 Jan 01 00:01 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:01 group + 2 files 144 bytes occupied + SHLL [/] # .. index:: CONFIGURE_SHELL_NO_COMMAND_CP .. index:: CONFIGURE_SHELL_COMMAND_CP -This command is included in the default shell command set. When building a -custom command set, define``CONFIGURE_SHELL_COMMAND_CP`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CP`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define``CONFIGURE_SHELL_COMMAND_CP`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CP`` when all shell commands have been + configured. .. index:: rtems_shell_main_cp -The ``cp`` command is implemented by a C language function which -has the following prototype: +PROGRAMMING INFORMATION: + The ``cp`` command is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_main_cp( + int argc, + char **argv + ); - int rtems_shell_main_cp( - int argc, - char **argv - ); + The configuration structure for the ``cp`` has the following prototype: -The configuration structure for the ``cp`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CP_Command; - extern rtems_shell_cmd_t rtems_shell_CP_Command; +ORIGIN: + The implementation and portions of the documentation for this command are + from NetBSD 4.0. -**ORIGIN:** +.. raw:: latex -The implementation and portions of the documentation for this command are from -NetBSD 4.0. + \clearpage .. _dd: @@ -712,252 +704,240 @@ dd - convert and copy a file ---------------------------- .. index:: dd -**SYNOPSYS:** - -.. code-block:: shell - - dd [operands ...] - -**DESCRIPTION:** - -The dd utility copies the standard input to the standard output. Input data is -read and written in 512-byte blocks. If input reads are short, input from -multiple reads are aggregated to form the output block. When finished, dd -displays the number of complete and partial input and output blocks and -truncated input records to the standard error output. - -The following operands are available: - -*bs=n* - Set both input and output block size, superseding the ibs and obs operands. - If no conversion values other than noerror, notrunc or sync are specified, - then each input block is copied to the output as a single block without any - aggregation of short blocks. - -*cbs=n* - Set the conversion record size to n bytes. The conversion record size is - required by the record oriented conversion values. - -*count=n* - Copy only n input blocks. - -*files=n* - Copy n input files before terminating. This operand is only applicable - when the input device is a tape. - -*ibs=n* - Set the input block size to n bytes instead of the default 512. - -*if=file* - Read input from file instead of the standard input. - -*obs=n* - Set the output block size to n bytes instead of the default 512. - -*of=file* - Write output to file instead of the standard output. Any regular output - file is truncated unless the notrunc conversion value is specified. If an - initial portion of the output file is skipped (see the seek operand) the - output file is truncated at that point. - -*seek=n* - Seek n blocks from the beginning of the output before copying. On non-tape - devices, a *lseek* operation is used. Otherwise, existing blocks are read - and the data discarded. If the seek operation is past the end of file, - space from the current end of file to the specified offset is filled with - blocks of NUL bytes. - -*skip=n* - Skip n blocks from the beginning of the input before copying. On input - which supports seeks, a *lseek* operation is used. Otherwise, input data - is read and discarded. For pipes, the correct number of bytes is read. - For all other devices, the correct number of blocks is read without - distinguishing between a partial or complete block being read. - -*progress=n* - Switch on display of progress if n is set to any non-zero value. This will - cause a "." to be printed (to the standard error output) for every n full - or partial blocks written to the output file. - -*conv=value[,value...]* - Where value is one of the symbols from the following list. - - *ascii, oldascii* - - The same as the unblock value except that characters are translated - from EBCDIC to ASCII before the records are converted. (These values - imply unblock if the operand cbs is also specified.) There are two - conversion maps for ASCII. The value ascii specifies the recom- mended - one which is compatible with AT&T System V UNIX. The value oldascii - specifies the one used in historic AT&T and pre 4.3BSD-Reno systems. - - *block* - - Treats the input as a sequence of newline or end-of-file terminated - variable length records independent of input and output block - boundaries. Any trailing newline character is discarded. Each input - record is converted to a fixed length output record where the length is - specified by the cbs operand. Input records shorter than the - conversion record size are padded with spaces. Input records longer - than the conversion record size are truncated. The number of truncated - input records, if any, are reported to the standard error output at the - completion of the copy. - - *ebcdic, ibm, oldebcdic, oldibm* - - The same as the block value except that characters are translated from - ASCII to EBCDIC after the records are converted. (These values imply - block if the operand cbs is also specified.) There are four conversion - maps for EBCDIC. The value ebcdic specifies the recommended one which - is compatible with AT&T System V UNIX. The value ibm is a slightly - different mapping, which is compatible with the AT&T System V UNIX ibm - value. The values oldebcdic and oldibm are maps used in historic AT&T - and pre 4.3BSD-Reno systems. - - *lcase* - - Transform uppercase characters into lowercase characters. - - *noerror* - - Do not stop processing on an input error. When an input error occurs, - a diagnostic message followed by the current input and output block - counts will be written to the standard error output in the same format - as the standard completion message. If the sync conversion is also - specified, any missing input data will be replaced with NUL bytes (or - with spaces if a block oriented conversion value was specified) and - processed as a normal input buffer. If the sync conversion is not - specified, the input block is omitted from the output. On input files - which are not tapes or pipes, the file offset will be positioned past - the block in which the error occurred using lseek(2). - - *notrunc* - - Do not truncate the output file. This will preserve any blocks in the - output file not explicitly written by dd. The notrunc value is not - supported for tapes. - - *osync* - - Pad the final output block to the full output block size. If the input - file is not a multiple of the output block size after conversion, this - conversion forces the final output block to be the same size as - preceding blocks for use on devices that require regularly sized blocks - to be written. This option is incompatible with use of the bs=n block - size specification. - - *sparse* - - If one or more non-final output blocks would consist solely of NUL - bytes, try to seek the output file by the required space instead of - filling them with NULs. This results in a sparse file on some file - systems. - - *swab* - - Swap every pair of input bytes. If an input buffer has an odd number - of bytes, the last byte will be ignored during swapping. - - *sync* - - Pad every input block to the input buffer size. Spaces are used for - pad bytes if a block oriented conversion value is specified, otherwise - NUL bytes are used. - - *ucase* - - Transform lowercase characters into uppercase characters. - - *unblock* - - Treats the input as a sequence of fixed length records independent of - input and output block boundaries. The length of the input records is - specified by the cbs operand. Any trailing space characters are - discarded and a newline character is appended. - -Where sizes are specified, a decimal number of bytes is expected. Two or more -numbers may be separated by an "x" to indicate a product. Each number may have -one of the following optional suffixes: - -*b* - Block; multiply by 512 - -*k* - Kibi; multiply by 1024 (1 KiB) - -*m* - Mebi; multiply by 1048576 (1 MiB) - -*g* - Gibi; multiply by 1073741824 (1 GiB) - -*t* - Tebi; multiply by 1099511627776 (1 TiB) - -*w* - Word; multiply by the number of bytes in an integer - -When finished, dd displays the number of complete and partial input and output -blocks, truncated input records and odd-length byte-swapping ritten. Partial -output blocks to tape devices are considered fatal errors. Otherwise, the rest -of the block will be written. Partial output blocks to character devices will -produce a warning message. A truncated input block is one where a variable -length record oriented conversion value was specified and the input line was -too long to fit in the conversion record or was not newline terminated. - -Normally, data resulting from input or conversion or both are aggregated into -output blocks of the specified size. After the end of input is reached, any -remaining output is written as a block. This means that the final output block -may be shorter than the output block size. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``dd``: - -.. code-block:: shell - - SHLL [/] $ dd if=/nfs/boot-image of=/dev/hda1 - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + dd [operands ...] + +DESCRIPTION: + The dd utility copies the standard input to the standard output. Input + data is read and written in 512-byte blocks. If input reads are short, + input from multiple reads are aggregated to form the output block. When + finished, dd displays the number of complete and partial input and output + blocks and truncated input records to the standard error output. + + The following operands are available: + + *bs=n* + Set both input and output block size, superseding the ibs and obs + operands. If no conversion values other than noerror, notrunc or sync + are specified, then each input block is copied to the output as a + single block without any aggregation of short blocks. + + *cbs=n* + Set the conversion record size to n bytes. The conversion record size + is required by the record oriented conversion values. + + *count=n* + Copy only n input blocks. + + *files=n* + Copy n input files before terminating. This operand is only applicable + when the input device is a tape. + + *ibs=n* + Set the input block size to n bytes instead of the default 512. + + *if=file* + Read input from file instead of the standard input. + + *obs=n* + Set the output block size to n bytes instead of the default 512. + + *of=file* + Write output to file instead of the standard output. Any regular + output file is truncated unless the notrunc conversion value is + specified. If an initial portion of the output file is skipped (see + the seek operand) the output file is truncated at that point. + + *seek=n* + Seek n blocks from the beginning of the output before copying. On + non-tape devices, a *lseek* operation is used. Otherwise, existing + blocks are read and the data discarded. If the seek operation is past + the end of file, space from the current end of file to the specified + offset is filled with blocks of NUL bytes. + + *skip=n* + Skip n blocks from the beginning of the input before copying. On input + which supports seeks, a *lseek* operation is used. Otherwise, input + data is read and discarded. For pipes, the correct number of bytes is + read. For all other devices, the correct number of blocks is read + without distinguishing between a partial or complete block being read. + + *progress=n* + Switch on display of progress if n is set to any non-zero value. This + will cause a "." to be printed (to the standard error output) for every + n full or partial blocks written to the output file. + + *conv=value[,value...]* + Where value is one of the symbols from the following list. + + *ascii, oldascii* + The same as the unblock value except that characters are translated + from EBCDIC to ASCII before the records are converted. (These + values imply unblock if the operand cbs is also specified.) There + are two conversion maps for ASCII. The value ascii specifies the + recom- mended one which is compatible with AT&T System V UNIX. The + value oldascii specifies the one used in historic AT&T and pre + 4.3BSD-Reno systems. + + *block* + Treats the input as a sequence of newline or end-of-file terminated + variable length records independent of input and output block + boundaries. Any trailing newline character is discarded. Each + input record is converted to a fixed length output record where the + length is specified by the cbs operand. Input records shorter than + the conversion record size are padded with spaces. Input records + longer than the conversion record size are truncated. The number + of truncated input records, if any, are reported to the standard + error output at the completion of the copy. + + *ebcdic, ibm, oldebcdic, oldibm* + The same as the block value except that characters are translated + from ASCII to EBCDIC after the records are converted. (These + values imply block if the operand cbs is also specified.) There + are four conversion maps for EBCDIC. The value ebcdic specifies + the recommended one which is compatible with AT&T System V UNIX. + The value ibm is a slightly different mapping, which is compatible + with the AT&T System V UNIX ibm value. The values oldebcdic and + oldibm are maps used in historic AT&T and pre 4.3BSD-Reno systems. + + *lcase* + Transform uppercase characters into lowercase characters. + + *noerror* + Do not stop processing on an input error. When an input error + occurs, a diagnostic message followed by the current input and + output block counts will be written to the standard error output in + the same format as the standard completion message. If the sync + conversion is also specified, any missing input data will be + replaced with NUL bytes (or with spaces if a block oriented + conversion value was specified) and processed as a normal input + buffer. If the sync conversion is not specified, the input block + is omitted from the output. On input files which are not tapes or + pipes, the file offset will be positioned past the block in which + the error occurred using lseek(2). + + *notrunc* + Do not truncate the output file. This will preserve any blocks in + the output file not explicitly written by dd. The notrunc value is + not supported for tapes. + + *osync* + Pad the final output block to the full output block size. If the + input file is not a multiple of the output block size after + conversion, this conversion forces the final output block to be the + same size as preceding blocks for use on devices that require + regularly sized blocks to be written. This option is incompatible + with use of the bs=n block size specification. + + *sparse* + If one or more non-final output blocks would consist solely of NUL + bytes, try to seek the output file by the required space instead of + filling them with NULs. This results in a sparse file on some file + systems. + + *swab* + Swap every pair of input bytes. If an input buffer has an odd + number of bytes, the last byte will be ignored during swapping. + + *sync* + Pad every input block to the input buffer size. Spaces are used + for pad bytes if a block oriented conversion value is specified, + otherwise NUL bytes are used. + + *ucase* + Transform lowercase characters into uppercase characters. + + *unblock* + Treats the input as a sequence of fixed length records independent + of input and output block boundaries. The length of the input + records is specified by the cbs operand. Any trailing space + characters are discarded and a newline character is appended. + + Where sizes are specified, a decimal number of bytes is expected. Two or + more numbers may be separated by an "x" to indicate a product. Each number + may have one of the following optional suffixes: + + *b* + Block; multiply by 512 + + *k* + Kibi; multiply by 1024 (1 KiB) + + *m* + Mebi; multiply by 1048576 (1 MiB) + + *g* + Gibi; multiply by 1073741824 (1 GiB) + + *t* + Tebi; multiply by 1099511627776 (1 TiB) + + *w* + Word; multiply by the number of bytes in an integer + + When finished, dd displays the number of complete and partial input and + output blocks, truncated input records and odd-length byte-swapping ritten. + Partial output blocks to tape devices are considered fatal errors. + Otherwise, the rest of the block will be written. Partial output blocks to + character devices will produce a warning message. A truncated input block + is one where a variable length record oriented conversion value was + specified and the input line was too long to fit in the conversion record + or was not newline terminated. + + Normally, data resulting from input or conversion or both are aggregated + into output blocks of the specified size. After the end of input is + reached, any remaining output is written as a block. This means that the + final output block may be shorter than the output block size. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + NONE + +EXAMPLES: + The following is an example of how to use ``dd``: + + .. code-block:: shell + + SHLL [/] $ dd if=/nfs/boot-image of=/dev/hda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_DD .. index:: CONFIGURE_SHELL_COMMAND_DD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DD`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DD`` to have this + command included. -This command can be excluded from the shell command set by -defining``CONFIGURE_SHELL_NO_COMMAND_DD`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by + defining``CONFIGURE_SHELL_NO_COMMAND_DD`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_dd -The ``dd`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``dd`` command is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_dd( + int argc, + char **argv + ); - int rtems_shell_rtems_main_dd( - int argc, - char **argv - ); + The configuration structure for the ``dd`` has the following prototype: -The configuration structure for the ``dd`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_DD_Command; - extern rtems_shell_cmd_t rtems_shell_DD_Command; +.. raw:: latex + + \clearpage .. _debugrfs: @@ -965,103 +945,100 @@ debugrfs - debug RFS file system -------------------------------- .. index:: debugrfs -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - debugrfs [-hl] path command [options] + debugrfs [-hl] path command [options] -**DESCRIPTION:** +DESCRIPTION: + The command provides debugging information for the RFS file system. -The command provides debugging information for the RFS file system. + The options are: -The options are: + *-h* + Print a help message. -*-h* - Print a help message. + *-l* + List the commands. -*-l* - List the commands. + *path* + Path to the mounted RFS file system. The file system has to be mounted + to view to use this command. -*path* - Path to the mounted RFS file system. The file system has to be mounted to - view to use this command. + The commands are: -The commands are: + *block start [end]* + Display the contents of the blocks from start to end. -*block start [end]* - Display the contents of the blocks from start to end. + *data* + Display the file system data and configuration. -*data* - Display the file system data and configuration. + *dir bno* + Process the block as a directory displaying the entries. -*dir bno* - Process the block as a directory displaying the entries. + *group start [end]* + Display the group data from the start group to the end group. -*group start [end]* - Display the group data from the start group to the end group. + *inode [-aef] [start] [end]* + Display the inodes between start and end. If no start and end is + provides all inodes are displayed. -*inode [-aef] [start] [end]* - Display the inodes between start and end. If no start and end is provides - all inodes are displayed. + *-a* + Display all inodes. That is allocated and unallocated inodes. - *-a* - Display all inodes. That is allocated and unallocated inodes. + *-e* + Search and display on inodes that have an error. - *-e* - Search and display on inodes that have an error. - - *-f* - Force display of inodes, even when in error. + *-f* + Force display of inodes, even when in error. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of how to use ``debugrfs``: -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``debugrfs``: - -.. code-block:: shell - - SHLL [/] $ debugrfs /c data - -**CONFIGURATION:** + SHLL [/] $ debugrfs /c data .. index:: CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS .. index:: CONFIGURE_SHELL_COMMAND_DEBUGRFS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DEBUGRFS`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DEBUGRFS`` to have + this command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_debugrfs -The ``debugrfs`` command is implemented by a C language function which -has the following prototype: +PROGRAMMING INFORMATION: + The ``debugrfs`` command is implemented by a C language function which has + the following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_debugrfs( - int argc, - char **argv - ); + int rtems_shell_rtems_main_debugrfs( + int argc, + char **argv + ); -The configuration structure for ``debugrfs`` has the following prototype: + The configuration structure for ``debugrfs`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command; + extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command; + +.. raw:: latex + + \clearpage .. _df: @@ -1069,71 +1046,69 @@ df - display file system disk space usage ----------------------------------------- .. index:: df -**SYNOPSYS:** - -.. code-block:: shell - - df [-h] [-B block_size] +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + df [-h] [-B block_size] -This command print disk space usage for mounted file systems. +DESCRIPTION: + This command print disk space usage for mounted file systems. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of how to use ``df``: -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``df``: - -.. code-block:: shell - - SHLL [/] $ df -B 4K - Filesystem 4K-blocks Used Available Use% Mounted on - /dev/rda 124 1 124 0% /mnt/ramdisk - SHLL [/] $ df - Filesystem 1K-blocks Used Available Use% Mounted on - /dev/rda 495 1 494 0% /mnt/ramdisk - SHLL [/] $ df -h - Filesystem Size Used Available Use% Mounted on - /dev/rda 495K 1K 494K 0% /mnt/ramdisk - -**CONFIGURATION:** + SHLL [/] $ df -B 4K + Filesystem 4K-blocks Used Available Use% Mounted on + /dev/rda 124 1 124 0% /mnt/ramdisk + SHLL [/] $ df + Filesystem 1K-blocks Used Available Use% Mounted on + /dev/rda 495 1 494 0% /mnt/ramdisk + SHLL [/] $ df -h + Filesystem Size Used Available Use% Mounted on + /dev/rda 495K 1K 494K 0% /mnt/ramdisk .. index:: CONFIGURE_SHELL_NO_COMMAND_DF .. index:: CONFIGURE_SHELL_COMMAND_DF -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DF`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DF`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DF`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DF`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_df -The ``df`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``df`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_main_df( - int argc, - char **argv - ); + int rtems_shell_main_df( + int argc, + char **argv + ); -The configuration structure for the ``df`` has the following prototype: + The configuration structure for the ``df`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_DF_Command; + extern rtems_shell_cmd_t rtems_shell_DF_Command; + +.. raw:: latex + + \clearpage .. _dir: @@ -1141,74 +1116,71 @@ dir - alias for ls ------------------ .. index:: dir -**SYNOPSYS:** - -.. code-block:: shell - - dir [dir] +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + dir [dir] -This command is an alias or alternate name for the ``ls``. See `ls - list -files in the directory` for more information. +DESCRIPTION: + This command is an alias or alternate name for the ``ls``. See `ls - list + files in the directory` for more information. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of how to use ``dir``: -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``dir``: - -.. code-block:: shell - - SHLL [/] $ dir - drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ - drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ - 2 files 1608 bytes occupied - SHLL [/] $ dir etc - -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:00 group - -rw-r--r-- 1 root root 30 Jan 01 00:00 issue - -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - -**CONFIGURATION:** + SHLL [/] $ dir + drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ + drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ + 2 files 1608 bytes occupied + SHLL [/] $ dir etc + -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:00 group + -rw-r--r-- 1 root root 30 Jan 01 00:00 issue + -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied .. index:: CONFIGURE_SHELL_NO_COMMAND_DIR .. index:: CONFIGURE_SHELL_COMMAND_DIR -This command is included in the default shell command set. -When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DIR`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DIR`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define``CONFIGURE_SHELL_COMMAND_DIR`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DIR`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_dir -The ``dir`` is implemented by a C language function -which has the following prototype: +PROGRAMMING INFORMATION: + The ``dir`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_dir( - int argc, - char **argv - ); + int rtems_shell_rtems_main_dir( + int argc, + char **argv + ); -The configuration structure for the ``dir`` has the following prototype: + The configuration structure for the ``dir`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_DIR_Command; + extern rtems_shell_cmd_t rtems_shell_DIR_Command; + +.. raw:: latex + + \clearpage .. _fdisk: @@ -1216,24 +1188,26 @@ fdisk - format disk ------------------- .. index:: fdisk -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - fdisk - -**CONFIGURATION:** + fdisk .. index:: CONFIGURE_SHELL_NO_COMMAND_FDISK .. index:: CONFIGURE_SHELL_COMMAND_FDISK -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_FDISK`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_FDISK`` to have this + command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all shell commands have been -configured. +.. raw:: latex + + \clearpage .. _hexdump: @@ -1241,256 +1215,254 @@ hexdump - ascii/dec/hex/octal dump ---------------------------------- .. index:: hexdump -**SYNOPSYS:** - -.. code-block:: shell - - hexdump [-bcCdovx] [-e format_string] [-f format_file] [-n length] [-s skip] file ... - -**DESCRIPTION:** - -The hexdump utility is a filter which displays the specified files, or the -standard input, if no files are specified, in a user specified format. - -The options are as follows: - -*-b* - One-byte octal display. Display the input offset in hexadecimal, followed - by sixteen space-separated, three column, zero-filled, bytes of input data, - in octal, per line. - -*-c* - One-byte character display. Display the input offset in hexadecimal, - followed by sixteen space-separated, three column, space-filled, characters - of input data per line. - -*-C* - Canonical hex+ASCII display. Display the input offset in hexadecimal, - followed by sixteen space-separated, two column, hexadecimal bytes, - followed by the same sixteen bytes in %_p format enclosed in "|" - characters. +SYNOPSYS: + .. code-block:: shell -*-d* - Two-byte decimal display. Display the input offset in hexadecimal, - followed by eight space-separated, five column, zero-filled, two-byte units - of input data, in unsigned decimal, per line. + hexdump [-bcCdovx] [-e format_string] [-f format_file] [-n length] [-s skip] file ... -*-e format_string* - Specify a format string to be used for displaying data. +DESCRIPTION: + The hexdump utility is a filter which displays the specified files, or the + standard input, if no files are specified, in a user specified format. -*-f format_file* - Specify a file that contains one or more newline separated format strings. - Empty lines and lines whose first non-blank character is a hash mark (#) - are ignored. + The options are as follows: -*-n length* - Interpret only length bytes of input. + *-b* + One-byte octal display. Display the input offset in hexadecimal, + followed by sixteen space-separated, three column, zero-filled, bytes + of input data, in octal, per line. -*-o* - Two-byte octal display. Display the input offset in hexadecimal, followed - by eight space-separated, six column, zerofilled, two byte quantities of - input data, in octal, per line. - -*-s offset* - Skip offset bytes from the beginning of the input. By default, offset is - interpreted as a decimal number. With a leading 0x or 0X, offset is - interpreted as a hexadecimal number, otherwise, with a leading 0, offset is - interpreted as an octal number. Appending the character b, k, or m to - offset causes it to be interpreted as a multiple of 512, 1024, or 1048576, - respectively. - -*-v* - The -v option causes hexdump to display all input data. Without the -v - option, any number of groups of output lines, which would be identical to - the immediately preceding group of output lines (except for the input - offsets), are replaced with a line containing a single asterisk. - -*-x* - Two-byte hexadecimal display. Display the input offset in hexadecimal, - followed by eight, space separated, four column, zero-filled, two-byte - quantities of input data, in hexadecimal, per line. - -For each input file, hexdump sequentially copies the input to standard output, -transforming the data according to the format strings specified by the -e and --f options, in the order that they were specified. - -*Formats* - -A format string contains any number of format units, separated by whitespace. -A format unit contains up to three items: an iteration count, a byte count, and -a format. - -The iteration count is an optional positive integer, which defaults to one. -Each format is applied iteration count times. - -The byte count is an optional positive integer. If specified it defines the -number of bytes to be interpreted by each iteration of the format. - -If an iteration count and/or a byte count is specified, a single slash must be -placed after the iteration count and/or before the byte count to disambiguate -them. Any whitespace before or after the slash is ignored. - -The format is required and must be surrounded by double quote (" ") marks. It -is interpreted as a fprintf-style format string (see*fprintf*), with the -following exceptions: - -- An asterisk (*) may not be used as a field width or precision. - -- A byte count or field precision is required for each "s" con- version - character (unlike the fprintf(3) default which prints the entire string if - the precision is unspecified). - -- The conversion characters "h", "l", "n", "p" and "q" are not supported. - -- The single character escape sequences described in the C standard are - supported: - - NUL \0 - \a - \b - \f - \n - \r - \t - \v - -Hexdump also supports the following additional conversion strings: - -*_a[dox]* - Display the input offset, cumulative across input files, of the next byte - to be displayed. The appended characters d, o, and x specify the display - base as decimal, octal or hexadecimal respectively. - -*_A[dox]* - Identical to the _a conversion string except that it is only performed - once, when all of the input data has been processed. - -*_c* - Output characters in the default character set. Nonprinting characters are - displayed in three character, zero-padded octal, except for those - representable by standard escape notation (see above), which are displayed - as two character strings. - -*_p* - Output characters in the default character set. Nonprinting characters are - displayed as a single ".". - -*_u* - Output US ASCII characters, with the exception that control characters are - displayed using the following, lower-case, names. Characters greater than - 0xff, hexadecimal, are displayed as hexadecimal strings. - - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``000`` nul|``001`` soh|``002`` stx|``003`` etx|``004`` eot|``005`` enq| - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``006`` ack|``007`` bel|``008`` bs |``009`` ht |``00A`` lf |``00B`` vt | - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``00C`` ff |``00D`` cr |``00E`` so |``00F`` si |``010`` dle|``011`` dc1| - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``012`` dc2|``013`` dc3|``014`` dc4|``015`` nak|``016`` syn|``017`` etb| - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``018`` can|``019`` em |``01A`` sub|``01B`` esc|``01C`` fs |``01D`` gs | - +-----------+-----------+-----------+-----------+-----------+-----------+ - |``01E`` rs |``01F`` us |``07F`` del| | | | - +-----------+-----------+-----------+-----------+-----------+-----------+ - -The default and supported byte counts for the conversion characters -are as follows: - - +----------------------+---------------------------------+ - |%_c, %_p, %_u, %c |One byte counts only. | - +----------------------+---------------------------------+ - |%d, %i, %o, %u, %X, %x|Four byte default, one, two, four| - | |and eight byte counts supported. | - +----------------------+---------------------------------+ - |%E, %e, %f, %G, %g |Eight byte default, four byte | - | |counts supported. | - +----------------------+---------------------------------+ + *-c* + One-byte character display. Display the input offset in hexadecimal, + followed by sixteen space-separated, three column, space-filled, + characters of input data per line. -The amount of data interpreted by each format string is the sum of the data -required by each format unit, which is the iteration count times the byte -count, or the iteration count times the number of bytes required by the format -if the byte count is not specified. + *-C* + Canonical hex+ASCII display. Display the input offset in hexadecimal, + followed by sixteen space-separated, two column, hexadecimal bytes, + followed by the same sixteen bytes in %_p format enclosed in "|" + characters. + + *-d* + Two-byte decimal display. Display the input offset in hexadecimal, + followed by eight space-separated, five column, zero-filled, two-byte + units of input data, in unsigned decimal, per line. -The input is manipulated in "blocks", where a block is defined as the largest -amount of data specified by any format string. Format strings interpreting -less than an input block's worth of data, whose last format unit both -interprets some number of bytes and does not have a specified iteration count, -have the iteration count incremented until the entire input block has been -processed or there is not enough data remaining in the block to satisfy the -format string. - -If, either as a result of user specification or hexdump modifying the iteration -count as described above, an iteration count is greater than one, no trailing -whitespace characters are output during the last iteration. - -It is an error to specify a byte count as well as multiple conversion -characters or strings unless all but one of the conversion characters or -strings is _a or _A. - -If, as a result of the specification of the -n option or end-of-file being -reached, input data only partially satisfies a format string, the input block -is zero-padded sufficiently to display all available data (i.e. any format -units overlapping the end of data will display some num- ber of the zero -bytes). - -Further output by such format strings is replaced by an equivalent number of -spaces. An equivalent number of spaces is defined as the number of spaces -output by an s conversion character with the same field width and precision as -the original conversion character or conversion string but with any "+", " ", -"#" conversion flag characters removed, and ref- erencing a NULL string. - -If no format strings are specified, the default display is equivalent to -specifying the -x option. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``hexdump``: - -.. code-block:: shell - - SHLL [/] $ hexdump -C -n 512 /dev/hda1 - -**CONFIGURATION:** + *-e format_string* + Specify a format string to be used for displaying data. + + *-f format_file* + Specify a file that contains one or more newline separated format + strings. Empty lines and lines whose first non-blank character is a + hash mark (#) are ignored. + + *-n length* + Interpret only length bytes of input. + + *-o* + Two-byte octal display. Display the input offset in hexadecimal, + followed by eight space-separated, six column, zerofilled, two byte + quantities of input data, in octal, per line. + + *-s offset* + Skip offset bytes from the beginning of the input. By default, offset + is interpreted as a decimal number. With a leading 0x or 0X, offset is + interpreted as a hexadecimal number, otherwise, with a leading 0, + offset is interpreted as an octal number. Appending the character b, + k, or m to offset causes it to be interpreted as a multiple of 512, + 1024, or 1048576, respectively. + + *-v* + The -v option causes hexdump to display all input data. Without the -v + option, any number of groups of output lines, which would be identical + to the immediately preceding group of output lines (except for the + input offsets), are replaced with a line containing a single asterisk. + + *-x* + Two-byte hexadecimal display. Display the input offset in hexadecimal, + followed by eight, space separated, four column, zero-filled, two-byte + quantities of input data, in hexadecimal, per line. + + For each input file, hexdump sequentially copies the input to standard + output, transforming the data according to the format strings specified by + the -e and -f options, in the order that they were specified. + + *Formats* + + A format string contains any number of format units, separated by + whitespace. A format unit contains up to three items: an iteration count, + a byte count, and a format. + + The iteration count is an optional positive integer, which defaults to one. + Each format is applied iteration count times. + + The byte count is an optional positive integer. If specified it defines + the number of bytes to be interpreted by each iteration of the format. + + If an iteration count and/or a byte count is specified, a single slash must + be placed after the iteration count and/or before the byte count to + disambiguate them. Any whitespace before or after the slash is ignored. + + The format is required and must be surrounded by double quote (" ") marks. + It is interpreted as a fprintf-style format string (see*fprintf*), with the + following exceptions: + + - An asterisk (*) may not be used as a field width or precision. + + - A byte count or field precision is required for each "s" con- version + character (unlike the fprintf(3) default which prints the entire string + if the precision is unspecified). + + - The conversion characters "h", "l", "n", "p" and "q" are not supported. + + - The single character escape sequences described in the C standard are + supported: + + NUL \0 + \a + \b + \f + \n + \r + \t + \v + + Hexdump also supports the following additional conversion strings: + + *_a[dox]* + Display the input offset, cumulative across input files, of the next + byte to be displayed. The appended characters d, o, and x specify the + display base as decimal, octal or hexadecimal respectively. + + *_A[dox]* + Identical to the _a conversion string except that it is only performed + once, when all of the input data has been processed. + + *_c* + Output characters in the default character set. Nonprinting characters + are displayed in three character, zero-padded octal, except for those + representable by standard escape notation (see above), which are + displayed as two character strings. + + *_p* + Output characters in the default character set. Nonprinting characters + are displayed as a single ".". + + *_u* + Output US ASCII characters, with the exception that control characters + are displayed using the following, lower-case, names. Characters + greater than 0xff, hexadecimal, are displayed as hexadecimal strings. + + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``000`` nul|``001`` soh|``002`` stx|``003`` etx|``004`` eot|``005`` enq| + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``006`` ack|``007`` bel|``008`` bs |``009`` ht |``00A`` lf |``00B`` vt | + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``00C`` ff |``00D`` cr |``00E`` so |``00F`` si |``010`` dle|``011`` dc1| + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``012`` dc2|``013`` dc3|``014`` dc4|``015`` nak|``016`` syn|``017`` etb| + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``018`` can|``019`` em |``01A`` sub|``01B`` esc|``01C`` fs |``01D`` gs | + +-----------+-----------+-----------+-----------+-----------+-----------+ + |``01E`` rs |``01F`` us |``07F`` del| | | | + +-----------+-----------+-----------+-----------+-----------+-----------+ + + The default and supported byte counts for the conversion characters are as + follows: + + +----------------------+---------------------------------+ + |%_c, %_p, %_u, %c |One byte counts only. | + +----------------------+---------------------------------+ + |%d, %i, %o, %u, %X, %x|Four byte default, one, two, four| + | |and eight byte counts supported. | + +----------------------+---------------------------------+ + |%E, %e, %f, %G, %g |Eight byte default, four byte | + | |counts supported. | + +----------------------+---------------------------------+ + + The amount of data interpreted by each format string is the sum of the data + required by each format unit, which is the iteration count times the byte + count, or the iteration count times the number of bytes required by the + format if the byte count is not specified. + + The input is manipulated in "blocks", where a block is defined as the + largest amount of data specified by any format string. Format strings + interpreting less than an input block's worth of data, whose last format + unit both interprets some number of bytes and does not have a specified + iteration count, have the iteration count incremented until the entire + input block has been processed or there is not enough data remaining in the + block to satisfy the format string. + + If, either as a result of user specification or hexdump modifying the + iteration count as described above, an iteration count is greater than one, + no trailing whitespace characters are output during the last iteration. + + It is an error to specify a byte count as well as multiple conversion + characters or strings unless all but one of the conversion characters or + strings is _a or _A. + + If, as a result of the specification of the -n option or end-of-file being + reached, input data only partially satisfies a format string, the input + block is zero-padded sufficiently to display all available data (i.e. any + format units overlapping the end of data will display some num- ber of the + zero bytes). + + Further output by such format strings is replaced by an equivalent number + of spaces. An equivalent number of spaces is defined as the number of + spaces output by an s conversion character with the same field width and + precision as the original conversion character or conversion string but + with any "+", " ", "#" conversion flag characters removed, and ref- + erencing a NULL string. + + If no format strings are specified, the default display is equivalent to + specifying the -x option. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + NONE + +EXAMPLES: + The following is an example of how to use ``hexdump``: + + .. code-block:: shell + + SHLL [/] $ hexdump -C -n 512 /dev/hda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_HEXDUMP .. index:: CONFIGURE_SHELL_COMMAND_HEXDUMP -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_HEXDUMP`` to have this -command included. - -This command can be excluded from the shell command set by -defining``CONFIGURE_SHELL_NO_COMMAND_HEXDUMP`` when all shell commands have -been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_HEXDUMP`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by + defining``CONFIGURE_SHELL_NO_COMMAND_HEXDUMP`` when all shell commands have + been configured. .. index:: rtems_shell_rtems_main_hexdump -The ``hexdump`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``hexdump`` command is implemented by a C language function which has + the following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_hexdump( + int argc, + char **argv + ); - int rtems_shell_rtems_main_hexdump( - int argc, - char **argv - ); + The configuration structure for the ``hexdump`` has the following prototype: -The configuration structure for the ``hexdump`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command; - extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command; +.. raw:: latex + + \clearpage .. _ln: @@ -1498,119 +1470,117 @@ ln - make links --------------- .. index:: ln -**SYNOPSYS:** - -.. code-block:: c - - ln [-fhinsv] source_file [target_file] - ln [-fhinsv] source_file ... target_dir - -**DESCRIPTION:** - -The ln utility creates a new directory entry (linked file) which has the same -modes as the original file. It is useful for maintaining multiple copies of a -file in many places at once without using up storage for the "copies"; instead, -a link "points" to the original copy. There are two types of links; hard links -and symbolic links. How a link "points" to a file is one of the differences -between a hard or symbolic link. - -The options are as follows: +SYNOPSYS: + .. code-block:: c -*-f* - Unlink any already existing file, permitting the link to occur. + ln [-fhinsv] source_file [target_file] + ln [-fhinsv] source_file ... target_dir -*-h* - If the target_file or target_dir is a symbolic link, do not follow it. - This is most useful with the -f option, to replace a symlink which may - point to a directory. +DESCRIPTION: + The ln utility creates a new directory entry (linked file) which has the + same modes as the original file. It is useful for maintaining multiple + copies of a file in many places at once without using up storage for the + "copies"; instead, a link "points" to the original copy. There are two + types of links; hard links and symbolic links. How a link "points" to a + file is one of the differences between a hard or symbolic link. -*-i* - Cause ln to write a prompt to standard error if the target file exists. If - the response from the standard input begins with the character 'y' or 'Y', - then unlink the target file so that the link may occur. Otherwise, do not - attempt the link. (The -i option overrides any previous -f options.) + The options are as follows: -*-n* - Same as -h, for compatibility with other ln implementations. - -*-s* - Create a symbolic link. + *-f* + Unlink any already existing file, permitting the link to occur. -*-v* - Cause ln to be verbose, showing files as they are processed. + *-h* + If the target_file or target_dir is a symbolic link, do not follow it. + This is most useful with the -f option, to replace a symlink which may + point to a directory. -By default ln makes hard links. A hard link to a file is indistinguishable -from the original directory entry; any changes to a file are effective -independent of the name used to reference the file. Hard links may not -normally refer to directories and may not span file systems. + *-i* + Cause ln to write a prompt to standard error if the target file exists. + If the response from the standard input begins with the character 'y' + or 'Y', then unlink the target file so that the link may occur. + Otherwise, do not attempt the link. (The -i option overrides any + previous -f options.) -A symbolic link contains the name of the file to which it is linked. The -referenced file is used when an *open* operation is performed on the link. A -*stat* on a symbolic link will return the linked-to file; an *lstat* must be -done to obtain information about the link. The *readlink* call may be used to -read the contents of a symbolic link. Symbolic links may span file systems and -may refer to directories. + *-n* + Same as -h, for compatibility with other ln implementations. -Given one or two arguments, ln creates a link to an existing file source_file. -If target_file is given, the link has that name; target_file may also be a -directory in which to place the link; otherwise it is placed in the current -directory. If only the directory is specified, the link will be made to the -last component of source_file. + *-s* + Create a symbolic link. -Given more than two arguments, ln makes links in target_dir to all the named -source files. The links made will have the same name as the files being linked -to. + *-v* + Cause ln to be verbose, showing files as they are processed. -**EXIT STATUS:** + By default ln makes hard links. A hard link to a file is indistinguishable + from the original directory entry; any changes to a file are effective + independent of the name used to reference the file. Hard links may not + normally refer to directories and may not span file systems. -The ``ln`` utility exits 0 on success, and >0 if an error occurs. + A symbolic link contains the name of the file to which it is linked. The + referenced file is used when an *open* operation is performed on the link. + A *stat* on a symbolic link will return the linked-to file; an *lstat* must + be done to obtain information about the link. The *readlink* call may be + used to read the contents of a symbolic link. Symbolic links may span file + systems and may refer to directories. -**NOTES:** + Given one or two arguments, ln creates a link to an existing file + source_file. If target_file is given, the link has that name; target_file + may also be a directory in which to place the link; otherwise it is placed + in the current directory. If only the directory is specified, the link + will be made to the last component of source_file. -None. + Given more than two arguments, ln makes links in target_dir to all the + named source files. The links made will have the same name as the files + being linked to. -**EXAMPLES:** +EXIT STATUS: + The ``ln`` utility exits 0 on success, and >0 if an error occurs. -.. code-block:: shell +NOTES: + None. - SHLL [/] ln -s /dev/console /dev/con1 +EXAMPLES: + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] ln -s /dev/console /dev/con1 .. index:: CONFIGURE_SHELL_NO_COMMAND_LN .. index:: CONFIGURE_SHELL_COMMAND_LN -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_LN`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_LN`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_LN`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_LN`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ln -The ``ln`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``ln`` command is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_ln( - int argc, - char **argv - ); + int rtems_shell_rtems_main_ln( + int argc, + char **argv + ); -The configuration structure for the ``ln`` has the following prototype: + The configuration structure for the ``ln`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_LN_Command; + extern rtems_shell_cmd_t rtems_shell_LN_Command; -**ORIGIN:** +ORIGIN: + The implementation and portions of the documentation for this command are + from NetBSD 4.0. -The implementation and portions of the documentation for this command are from -NetBSD 4.0. +.. raw:: latex + + \clearpage .. _ls: @@ -1618,77 +1588,76 @@ ls - list files in the directory -------------------------------- .. index:: ls -**SYNOPSYS:** - -.. code-block:: shell - - ls [dir] - -**DESCRIPTION:** - -This command displays the contents of the specified directory. If no arguments -are given, then it displays the contents of the current working directory. - -**EXIT STATUS:** +SYNOPSYS: + .. code-block:: shell -This command returns 0 on success and non-zero if an error is encountered. + ls [dir] -**NOTES:** +DESCRIPTION: + This command displays the contents of the specified directory. If no + arguments are given, then it displays the contents of the current working + directory. -This command currently does not display information on a set of files like the -POSIX ls(1). It only displays the contents of entire directories. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + This command currently does not display information on a set of files like + the POSIX ls(1). It only displays the contents of entire directories. -The following is an example of how to use ``ls``: +EXAMPLES: + The following is an example of how to use ``ls``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ ls - drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ - drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ - 2 files 1608 bytes occupied - SHLL [/] $ ls etc - -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd - -rw-r--r-- 1 root root 42 Jan 01 00:00 group - -rw-r--r-- 1 root root 30 Jan 01 00:00 issue - -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net - 4 files 202 bytes occupied - SHLL [/] $ ls dev etc - -rwxr-xr-x 1 rtems root 0 Jan 01 00:00 console - -rwxr-xr-x 1 root root 0 Jan 01 00:00 console_b - -**CONFIGURATION:** + SHLL [/] $ ls + drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ + drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ + 2 files 1608 bytes occupied + SHLL [/] $ ls etc + -rw-r--r-- 1 root root 102 Jan 01 00:00 passwd + -rw-r--r-- 1 root root 42 Jan 01 00:00 group + -rw-r--r-- 1 root root 30 Jan 01 00:00 issue + -rw-r--r-- 1 root root 28 Jan 01 00:00 issue.net + 4 files 202 bytes occupied + SHLL [/] $ ls dev etc + -rwxr-xr-x 1 rtems root 0 Jan 01 00:00 console + -rwxr-xr-x 1 root root 0 Jan 01 00:00 console_b .. index:: CONFIGURE_SHELL_NO_COMMAND_LS .. index:: CONFIGURE_SHELL_COMMAND_LS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_LS`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_LS`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_LS`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_LS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ls -The ``ls`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``ls`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_ls( + int argc, + char **argv + ); - int rtems_shell_rtems_main_ls( - int argc, - char **argv - ); + The configuration structure for the ``ls`` has the following prototype: -The configuration structure for the ``ls`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_LS_Command; - extern rtems_shell_cmd_t rtems_shell_LS_Command; +.. raw:: latex + + \clearpage .. _md5: @@ -1696,66 +1665,64 @@ md5 - compute the Md5 hash of a file or list of files ----------------------------------------------------- .. index:: md5 -**SYNOPSYS:** - -.. code-block:: shell - - md5 - -**DESCRIPTION:** - -This command prints the MD5 of a file. You can provide one or more files on the -command line and a hash for each file is printed in a single line of output. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: shell -**NOTES:** + md5 -None. +DESCRIPTION: + This command prints the MD5 of a file. You can provide one or more files on + the command line and a hash for each file is printed in a single line of + output. -**EXAMPLES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The following is an example of how to use ``md5``: +NOTES: + None. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``md5``: - SHLL [/] $ md5 shell-init - MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31 + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] $ md5 shell-init + MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31 .. index:: CONFIGURE_SHELL_NO_COMMAND_MD5 .. index:: CONFIGURE_SHELL_COMMAND_MD5 -This command is included in the default shell command set. When building a -custom command set, define``CONFIGURE_SHELL_COMMAND_MD5`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define``CONFIGURE_SHELL_COMMAND_MD5`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MD5`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MD5`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_md5 -The ``md5`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``md5`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c + + int rtems_shell_main_md5( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``md5`` has the following prototype: - int rtems_shell_main_md5( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``md5`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_MD5_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_MD5_Command; + \clearpage .. _mkdir: @@ -1763,81 +1730,78 @@ mkdir - create a directory -------------------------- .. index:: mkdir -**SYNOPSYS:** - -.. code-block:: c - - mkdir dir [dir1 .. dirN] - -**DESCRIPTION:** - -This command creates the set of directories in the order they are specified on -the command line. If an error is encountered making one of the directories, -the command will continue to attempt to create the remaining directories on the -command line. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: c -**NOTES:** + mkdir dir [dir1 .. dirN] -If this command is invoked with no arguments, nothing occurs. +DESCRIPTION: + This command creates the set of directories in the order they are specified + on the command line. If an error is encountered making one of the + directories, the command will continue to attempt to create the remaining + directories on the command line. -The user must have sufficient permissions to create the directory. For the -``fileio`` test provided with RTEMS, this means the user must login as ``root`` -not ``rtems``. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + If this command is invoked with no arguments, nothing occurs. -The following is an example of how to use ``mkdir``: + The user must have sufficient permissions to create the directory. For the + ``fileio`` test provided with RTEMS, this means the user must login as + ``root`` not ``rtems``. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``mkdir``: - SHLL [/] # ls - drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ - drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ - 2 files 1608 bytes occupied - SHLL [/] # mkdir joel - SHLL [/] # ls joel - 0 files 0 bytes occupied - SHLL [/] # cp etc/passwd joel - SHLL [/] # ls joel - -rw-r--r-- 1 root root 102 Jan 01 00:02 passwd - 1 files 102 bytes occupied + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] # ls + drwxr-xr-x 1 root root 536 Jan 01 00:00 dev/ + drwxr-xr-x 1 root root 1072 Jan 01 00:00 etc/ + 2 files 1608 bytes occupied + SHLL [/] # mkdir joel + SHLL [/] # ls joel + 0 files 0 bytes occupied + SHLL [/] # cp etc/passwd joel + SHLL [/] # ls joel + -rw-r--r-- 1 root root 102 Jan 01 00:02 passwd + 1 files 102 bytes occupied .. index:: CONFIGURE_SHELL_NO_COMMAND_MKDIR .. index:: CONFIGURE_SHELL_COMMAND_MKDIR -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MKDIR`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MKDIR`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MKDIR`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MKDIR`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mkdir -The ``mkdir`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mkdir`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_mkdir( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``mkdir`` has the following prototype: - int rtems_shell_rtems_main_mkdir( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``mkdir`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_MKDIR_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_MKDIR_Command; + \clearpage .. _mkdos: @@ -1845,76 +1809,73 @@ mkdos - DOSFS file system format -------------------------------- .. index:: mkdos -**SYNOPSYS:** - -.. code-block:: shell - - mkdos [-V label] [-s sectors/cluster] [-r size] [-v] path - -**DESCRIPTION:** - -This command formats a block device entry with the DOSFS file system. - -*-V label* - Specify the volume label. - -*-s sectors/cluster* - Specify the number of sectors per cluster. +SYNOPSYS: + .. code-block:: shell -*-r size* - Specify the number of entries in the root directory. + mkdos [-V label] [-s sectors/cluster] [-r size] [-v] path -*-v* - Enable verbose output mode. +DESCRIPTION: + This command formats a block device entry with the DOSFS file system. -**EXIT STATUS:** + *-V label* + Specify the volume label. -This command returns 0 on success and non-zero if an error is encountered. + *-s sectors/cluster* + Specify the number of sectors per cluster. -**NOTES:** + *-r size* + Specify the number of entries in the root directory. -None. + *-v* + Enable verbose output mode. -**EXAMPLES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The following is an example of how to use ``mkdos``: +NOTES: + None. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``mkdos``: - SHLL [/] $ mkdos /dev/rda1 + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] $ mkdos /dev/rda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_MKDOS .. index:: CONFIGURE_SHELL_COMMAND_MKDOS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MKDOS`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MKDOS`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MKDOS`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MKDOS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mkdos -The ``mkdos`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mkdos`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_mkdos( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``mkdos`` has the following prototype: - int rtems_shell_rtems_main_mkdos( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``mkdos`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_MKDOS_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_MKDOS_Command; + \clearpage .. _mknod: @@ -1922,129 +1883,125 @@ mknod - make device special file -------------------------------- .. index:: mknod -**SYNOPSYS:** - -.. code-block:: shell - - mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b] [driver | major] minor - mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b] major unit subunit - mknod [-rR] [-g gid] [-m mode] [-u uid] name [c | b] number - mknod [-rR] [-g gid] [-m mode] [-u uid] name p - -**DESCRIPTION:** - -The mknod command creates device special files, or fifos. Normally the shell -script /dev/MAKEDEV is used to create special files for commonly known devices; -it executes mknod with the appropriate arguments and can make all the files -required for the device. - -To make nodes manually, the arguments are: - -*-r* - Replace an existing file if its type is incorrect. +SYNOPSYS: + .. code-block:: shell -*-R* - Replace an existing file if its type is incorrect. Correct the mode, user - and group. + mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b] [driver | major] minor + mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b] major unit subunit + mknod [-rR] [-g gid] [-m mode] [-u uid] name [c | b] number + mknod [-rR] [-g gid] [-m mode] [-u uid] name p -*-g gid* - Specify the group for the device node. The gid operand may be a numeric - group ID or a group name. If a group name is also a numeric group ID, the - operand is used as a group name. Precede a numeric group ID with a # to - stop it being treated as a name. +DESCRIPTION: + The mknod command creates device special files, or fifos. Normally the + shell script /dev/MAKEDEV is used to create special files for commonly + known devices; it executes mknod with the appropriate arguments and can + make all the files required for the device. -*-m mode* - Specify the mode for the device node. The mode may be absolute or - symbolic, see *chmod*. + To make nodes manually, the arguments are: -*-u uid* - Specify the user for the device node. The uid operand may be a numeric - user ID or a user name. If a user name is also a numeric user ID, the - operand is used as a user name. Precede a numeric user ID with a # to stop - it being treated as a name. + *-r* + Replace an existing file if its type is incorrect. -*name* - Device name, for example "tty" for a termios serial device or "hd" for a - disk. + *-R* + Replace an existing file if its type is incorrect. Correct the mode, + user and group. -*b | c | p* - Type of device. If the device is a block type device such as a tape or - disk drive which needs both cooked and raw special files, the type is b. - All other devices are character type devices, such as terminal and pseudo - devices, and are type c. Specifying p creates fifo files. + *-g gid* + Specify the group for the device node. The gid operand may be a + numeric group ID or a group name. If a group name is also a numeric + group ID, the operand is used as a group name. Precede a numeric group + ID with a # to stop it being treated as a name. -*driver | major* - The major device number is an integer number which tells the kernel which - device driver entry point to use. If the device driver is configured into - the current kernel it may be specified by driver name or major number. + *-m mode* + Specify the mode for the device node. The mode may be absolute or + symbolic, see *chmod*. -*minor* - The minor device number tells the kernel which one of several similar - devices the node corresponds to; for example, it may be a specific serial - port or pty. + *-u uid* + Specify the user for the device node. The uid operand may be a numeric + user ID or a user name. If a user name is also a numeric user ID, the + operand is used as a user name. Precede a numeric user ID with a # to + stop it being treated as a name. -*unit and subunit* - The unit and subunit numbers select a subset of a device; for example, the - unit may specify a particular disk, and the subunit a partition on that - disk. (Currently this form of specification is only supported by the bsdos - format, for compatibility with the BSD/OS mknod). + *name* + Device name, for example "tty" for a termios serial device or "hd" for + a disk. -*number* + *b | c | p* + Type of device. If the device is a block type device such as a tape or + disk drive which needs both cooked and raw special files, the type + is b. All other devices are character type devices, such as terminal + and pseudo devices, and are type c. Specifying p creates fifo files. - A single opaque device number. Useful for netbooted computers which - require device numbers packed in a format that isn't supported by -F. + *driver | major* + The major device number is an integer number which tells the kernel + which device driver entry point to use. If the device driver is + configured into the current kernel it may be specified by driver name + or major number. -**EXIT STATUS:** + *minor* + The minor device number tells the kernel which one of several similar + devices the node corresponds to; for example, it may be a specific + serial port or pty. -The ``mknod`` utility exits 0 on success, and >0 if an error occurs. + *unit and subunit* + The unit and subunit numbers select a subset of a device; for example, + the unit may specify a particular disk, and the subunit a partition on + that disk. (Currently this form of specification is only supported by + the bsdos format, for compatibility with the BSD/OS mknod). -**NOTES:** + *number* + A single opaque device number. Useful for netbooted computers which + require device numbers packed in a format that isn't supported by -F. -None. +EXIT STATUS: + The ``mknod`` utility exits 0 on success, and >0 if an error occurs. -**EXAMPLES:** +NOTES: + None. -.. code-block:: shell +EXAMPLES: + .. code-block:: shell - SHLL [/] mknod c 3 0 /dev/ttyS10 - -**CONFIGURATION:** + SHLL [/] mknod c 3 0 /dev/ttyS10 .. index:: CONFIGURE_SHELL_NO_COMMAND_MKNOD .. index:: CONFIGURE_SHELL_COMMAND_MKNOD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MKNOD`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MKNOD`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MKNOD`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MKNOD`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mknod -The ``mknod`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``mknod`` command is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_mknod( + int argc, + char **argv + ); - int rtems_shell_rtems_main_mknod( - int argc, - char **argv - ); + The configuration structure for the ``mknod`` has the following prototype: -The configuration structure for the ``mknod`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MKNOD_Command; - extern rtems_shell_cmd_t rtems_shell_MKNOD_Command; +ORIGIN: + The implementation and portions of the documentation for this command are + from NetBSD 4.0. -**ORIGIN:** +.. raw:: latex -The implementation and portions of the documentation for this command are from -NetBSD 4.0. + \clearpage .. _mkrfs: @@ -2052,97 +2009,94 @@ mkrfs - format RFS file system ------------------------------ .. index:: mkrfs -**SYNOPSYS:** - -.. code-block:: shell - - mkrfs [-vsbiIo] device +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + mkrfs [-vsbiIo] device -Format the block device with the RTEMS File System (RFS). The default -configuration with not parameters selects a suitable block size based on the -size of the media being formatted. +DESCRIPTION: + Format the block device with the RTEMS File System (RFS). The default + configuration with not parameters selects a suitable block size based on + the size of the media being formatted. -The media is broken up into groups of blocks. The number of blocks in a group -is based on the number of bits a block contains. The large a block the more -blocks a group contains and the fewer groups in the file system. + The media is broken up into groups of blocks. The number of blocks in a + group is based on the number of bits a block contains. The large a block + the more blocks a group contains and the fewer groups in the file system. -The following options are provided: + The following options are provided: -*-v* - Display configuration and progress of the format. + *-v* + Display configuration and progress of the format. -*-s* - Set the block size in bytes. + *-s* + Set the block size in bytes. -*-b* - The number of blocks in a group. The block count must be equal or less than - the number of bits in a block. + *-b* + The number of blocks in a group. The block count must be equal or less + than the number of bits in a block. -*-i* - Number of inodes in a group. The inode count must be equal or less than the - number of bits in a block. + *-i* + Number of inodes in a group. The inode count must be equal or less than + the number of bits in a block. -*-I* - Initialise the inodes. The default is not to initialise the inodes and to - rely on the inode being initialised when allocated. Initialising the inode - table helps recovery if a problem appears. + *-I* + Initialise the inodes. The default is not to initialise the inodes and + to rely on the inode being initialised when allocated. Initialising the + inode table helps recovery if a problem appears. -*-o* - Integer percentage of the media used by inodes. The default is 1%. + *-o* + Integer percentage of the media used by inodes. The default is 1%. -*device* - Path of the device to format. + *device* + Path of the device to format. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + None. -**NOTES:** +EXAMPLES: + The following is an example of how to use ``mkrfs``: -None. + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``mkrfs``: - -.. code-block:: shell - - SHLL [/] $ mkrfs /dev/fdda - -**CONFIGURATION:** + SHLL [/] $ mkrfs /dev/fdda .. index:: CONFIGURE_SHELL_NO_COMMAND_MKRFS .. index:: CONFIGURE_SHELL_COMMAND_MKRFS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MKRFS`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MKRFS`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MKRFS`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MKRFS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_mkrfs -The ``mkrfs`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``mkrfs`` command is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_mkrfs( - int argc, - char **argv - ); + int rtems_shell_rtems_main_mkrfs( + int argc, + char **argv + ); -The configuration structure for ``mkrfs`` has the following prototype: + The configuration structure for ``mkrfs`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MKRFS_Command; + extern rtems_shell_cmd_t rtems_shell_MKRFS_Command; + +.. raw:: latex + + \clearpage .. _mount: @@ -2150,128 +2104,127 @@ mount - mount disk ------------------ .. index:: mount -**SYNOPSYS:** - -.. code-block:: shell - - mount [-t fstype] [-r] [-L] device path - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -The ``mount`` command will mount a block device to a mount point using the -specified file system. The files systems are: + mount [-t fstype] [-r] [-L] device path -- msdos - MSDOS File System +DESCRIPTION: + The ``mount`` command will mount a block device to a mount point using the + specified file system. The files systems are: -- tftp - TFTP Network File System + - msdos - MSDOS File System -- ftp - FTP Network File System + - tftp - TFTP Network File System -- nfs - Network File System + - ftp - FTP Network File System -- rfs - RTEMS File System + - nfs - Network File System -When the file system type is 'msdos' or 'rfs' the driver is a "block device -driver" node present in the file system. The driver is ignored with the 'tftp' -and 'ftp' file systems. For the 'nfs' file system the driver is the -'host:/path' string that described NFS host and the exported file system path. + - rfs - RTEMS File System -**EXIT STATUS:** + When the file system type is 'msdos' or 'rfs' the driver is a "block device + driver" node present in the file system. The driver is ignored with the + 'tftp' and 'ftp' file systems. For the 'nfs' file system the driver is the + 'host:/path' string that described NFS host and the exported file system + path. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + The mount point must exist. -The mount point must exist. + The services offered by each file-system vary. For example you cannot list + the directory of a TFTP file-system as this server is not provided in the + TFTP protocol. You need to check each file-system's documentation for the + services provided. -The services offered by each file-system vary. For example you cannot list the -directory of a TFTP file-system as this server is not provided in the TFTP -protocol. You need to check each file-system's documentation for the services -provided. +EXAMPLES: + Mount the Flash Disk driver to the '/fd' mount point: -**EXAMPLES:** + .. code-block:: shell -Mount the Flash Disk driver to the '/fd' mount point: + SHLL [/] $ mount -t msdos /dev/flashdisk0 /fd -.. code-block:: shell + Mount the NFS file system exported path 'bar' by host 'foo': - SHLL [/] $ mount -t msdos /dev/flashdisk0 /fd + .. code-block:: shell -Mount the NFS file system exported path 'bar' by host 'foo': + $ mount -t nfs foo:/bar /nfs -.. code-block:: shell + Mount the TFTP file system on '/tftp': - $ mount -t nfs foo:/bar /nfs + .. code-block:: shell -Mount the TFTP file system on '/tftp': + $ mount -t tftp /tftp -.. code-block:: shell + To access the TFTP files on server '10.10.10.10': + .. code-block:: shell - $ mount -t tftp /tftp - -To access the TFTP files on server '10.10.10.10': -.. code-block:: shell - - $ cat /tftp/10.10.10.10/test.txt - -**CONFIGURATION:** + $ cat /tftp/10.10.10.10/test.txt .. index:: CONFIGURE_SHELL_NO_COMMAND_MOUNT .. index:: CONFIGURE_SHELL_COMMAND_MOUNT -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MOUNT`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MOUNT`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MOUNT`` to have this + command included. -The mount command includes references to file-system code. If you do not wish -to include file-system that you do not use do not define the mount command -support for that file-system. The file-system mount command defines are: + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MOUNT`` when all shell commands have been + configured. -- msdos - CONFIGURE_SHELL_MOUNT_MSDOS + The mount command includes references to file-system code. If you do not + wish to include file-system that you do not use do not define the mount + command support for that file-system. The file-system mount command defines + are: -- tftp - CONFIGURE_SHELL_MOUNT_TFTP + - msdos - CONFIGURE_SHELL_MOUNT_MSDOS -- ftp - CONFIGURE_SHELL_MOUNT_FTP + - tftp - CONFIGURE_SHELL_MOUNT_TFTP -- nfs - CONFIGURE_SHELL_MOUNT_NFS + - ftp - CONFIGURE_SHELL_MOUNT_FTP -- rfs - CONFIGURE_SHELL_MOUNT_RFS + - nfs - CONFIGURE_SHELL_MOUNT_NFS -An example configuration is: + - rfs - CONFIGURE_SHELL_MOUNT_RFS -.. code-block:: c + An example configuration is: - #define CONFIGURE_SHELL_MOUNT_MSDOS - #ifdef RTEMS_NETWORKING - #define CONFIGURE_SHELL_MOUNT_TFTP - #define CONFIGURE_SHELL_MOUNT_FTP - #define CONFIGURE_SHELL_MOUNT_NFS - #define CONFIGURE_SHELL_MOUNT_RFS - #endif + .. code-block:: c -**PROGRAMMING INFORMATION:** + #define CONFIGURE_SHELL_MOUNT_MSDOS + #ifdef RTEMS_NETWORKING + #define CONFIGURE_SHELL_MOUNT_TFTP + #define CONFIGURE_SHELL_MOUNT_FTP + #define CONFIGURE_SHELL_MOUNT_NFS + #define CONFIGURE_SHELL_MOUNT_RFS + #endif .. index:: rtems_shell_rtems_main_mount -The ``mount`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``mount`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_mount( - int argc, - char **argv - ); + int rtems_shell_rtems_main_mount( + int argc, + char **argv + ); -The configuration structure for the ``mount`` has the following prototype: + The configuration structure for the ``mount`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MOUNT_Command; + extern rtems_shell_cmd_t rtems_shell_MOUNT_Command; + +.. raw:: latex + + \clearpage .. _mv: @@ -2279,109 +2232,107 @@ mv - move files --------------- .. index:: mv -**SYNOPSYS:** - -.. code-block:: shell - - mv [-fiv] source_file target_file - mv [-fiv] source_file... target_file - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -In its first form, the mv utility renames the file named by the source operand -to the destination path named by the target operand. This form is assumed when -the last operand does not name an already existing directory. + mv [-fiv] source_file target_file + mv [-fiv] source_file... target_file -In its second form, mv moves each file named by a source operand to a -destination file in the existing directory named by the directory operand. The -destination path for each operand is the pathname produced by the concatenation -of the last operand, a slash, and the final pathname component of the named -file. +DESCRIPTION: + In its first form, the mv utility renames the file named by the source + operand to the destination path named by the target operand. This form is + assumed when the last operand does not name an already existing directory. -The following options are available: + In its second form, mv moves each file named by a source operand to a + destination file in the existing directory named by the directory operand. + The destination path for each operand is the pathname produced by the + concatenation of the last operand, a slash, and the final pathname + component of the named file. -*-f* - Do not prompt for confirmation before overwriting the destination path. + The following options are available: -*-i* - Causes mv to write a prompt to standard error before moving a file that - would overwrite an existing file. If the response from the standard input - begins with the character 'y', the move is attempted. - -*-v* - Cause mv to be verbose, showing files as they are processed. - -The last of any -f or -i options is the one which affects mv's behavior. - -It is an error for any of the source operands to specify a nonexistent file or -directory. + *-f* + Do not prompt for confirmation before overwriting the destination path. -It is an error for the source operand to specify a directory if the target -exists and is not a directory. + *-i* + Causes mv to write a prompt to standard error before moving a file that + would overwrite an existing file. If the response from the standard + input begins with the character 'y', the move is attempted. -If the destination path does not have a mode which permits writing, mv prompts -the user for confirmation as specified for the -i option. + *-v* + Cause mv to be verbose, showing files as they are processed. -Should the *rename* call fail because source and target are on different file -systems, ``mv`` will remove the destination file, copy the source file to the -destination, and then remove the source. The effect is roughly equivalent to: + The last of any -f or -i options is the one which affects mv's behavior. -.. code-block:: shell + It is an error for any of the source operands to specify a nonexistent file + or directory. - rm -f destination_path && \ - cp -PRp source_file destination_path && \ - rm -rf source_file + It is an error for the source operand to specify a directory if the target + exists and is not a directory. -**EXIT STATUS:** + If the destination path does not have a mode which permits writing, mv + prompts the user for confirmation as specified for the -i option. -The ``mv`` utility exits 0 on success, and >0 if an error occurs. + Should the *rename* call fail because source and target are on different + file systems, ``mv`` will remove the destination file, copy the source file + to the destination, and then remove the source. The effect is roughly + equivalent to: -**NOTES:** + .. code-block:: shell -None. + rm -f destination_path && \ + cp -PRp source_file destination_path && \ + rm -rf source_file -**EXAMPLES:** +EXIT STATUS: + The ``mv`` utility exits 0 on success, and >0 if an error occurs. -.. code-block:: shell +NOTES: + None. - SHLL [/] mv /dev/console /dev/con1 +EXAMPLES: + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] mv /dev/console /dev/con1 .. index:: CONFIGURE_SHELL_NO_COMMAND_MV .. index:: CONFIGURE_SHELL_COMMAND_MV -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_MV`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_MV`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MV`` when all shell commands have been configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MV`` when all shell commands have been + configured. .. index:: rtems_shell_main_mv -The ``mv`` command is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``mv`` command is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_main_mv( + int argc, + char **argv + ); - int rtems_shell_main_mv( - int argc, - char **argv - ); + The configuration structure for the ``mv`` has the following prototype: -The configuration structure for the ``mv`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MV_Command; - extern rtems_shell_cmd_t rtems_shell_MV_Command; +ORIGIN: + The implementation and portions of the documentation for this command are + from NetBSD 4.0. -**ORIGIN:** +.. raw:: latex -The implementation and portions of the documentation for this command are from -NetBSD 4.0. + \clearpage .. _pwd: @@ -2389,139 +2340,133 @@ pwd - print work directory -------------------------- .. index:: pwd -**SYNOPSYS:** - -.. code-block:: shell - - pwd - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command prints the fully qualified filename of the current working -directory. + pwd -**EXIT STATUS:** +DESCRIPTION: + This command prints the fully qualified filename of the current working + directory. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + None. -None. +EXAMPLES: + The following is an example of how to use ``pwd``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``pwd``: - -.. code-block:: shell - - SHLL [/] $ pwd - / - SHLL [/] $ cd dev - SHLL [/dev] $ pwd - /dev - -**CONFIGURATION:** + SHLL [/] $ pwd + / + SHLL [/] $ cd dev + SHLL [/dev] $ pwd + /dev .. index:: CONFIGURE_SHELL_NO_COMMAND_PWD .. index:: CONFIGURE_SHELL_COMMAND_PWD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_PWD`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PWD`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_PWD`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PWD`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_pwd -The ``pwd`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``pwd`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_pwd( - int argc, - char **argv - ); + int rtems_shell_rtems_main_pwd( + int argc, + char argv + ); -The configuration structure for the ``pwd`` has the following prototype: + The configuration structure for the ``pwd`` has the following prototype: -.. code-block:: c + .. code-block:: c extern rtems_shell_cmd_t rtems_shell_PWD_Command; +.. raw:: latex + + \clearpage + .. _rmdir: rmdir - remove empty directories -------------------------------- .. index:: rmdir -**SYNOPSYS:** - -.. code-block:: shell - - rmdir [dir1 .. dirN] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command removes the specified set of directories. If no directories are -provided on the command line, no actions are taken. + rmdir [dir1 .. dirN] -**EXIT STATUS:** +DESCRIPTION: + This command removes the specified set of directories. If no directories + are provided on the command line, no actions are taken. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + This command is a implemented using the ``rmdir(2)`` system call and all + reasons that call may fail apply to this command. -This command is a implemented using the ``rmdir(2)`` system call and all -reasons that call may fail apply to this command. +EXAMPLES: + The following is an example of how to use ``rmdir``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``rmdir``: - -.. code-block:: shell - - SHLL [/] # mkdir joeldir - SHLL [/] # rmdir joeldir - SHLL [/] # ls joeldir - joeldir: No such file or directory. - -**CONFIGURATION:** + SHLL [/] # mkdir joeldir + SHLL [/] # rmdir joeldir + SHLL [/] # ls joeldir + joeldir: No such file or directory. .. index:: CONFIGURE_SHELL_NO_COMMAND_RMDIR .. index:: CONFIGURE_SHELL_COMMAND_RMDIR -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_RMDIR`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_RMDIR`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_RMDIR`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_RMDIR`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_rmdir -The ``rmdir`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``rmdir`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_rmdir( - int argc, - char **argv - ); + int rtems_shell_rtems_main_rmdir( + int argc, + char **argv + ); -The configuration structure for the ``rmdir`` has the following prototype: + The configuration structure for the ``rmdir`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_RMDIR_Command; + extern rtems_shell_cmd_t rtems_shell_RMDIR_Command; + +.. raw:: latex + + \clearpage .. _rm: @@ -2529,77 +2474,75 @@ rm - remove files ----------------- .. index:: rm -**SYNOPSYS:** - -.. code-block:: shell - - rm file1 [file2 ... fileN] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command deletes a name from the filesystem. If the specified file name -was the last link to a file and there are no ``open`` file descriptor -references to that file, then it is deleted and the associated space in the -file system is made available for subsequent use. + rm file1 [file2 ... fileN] -If the filename specified was the last link to a file but there are open file -descriptor references to it, then the file will remain in existence until the -last file descriptor referencing it is closed. +DESCRIPTION: + This command deletes a name from the filesystem. If the specified file + name was the last link to a file and there are no ``open`` file descriptor + references to that file, then it is deleted and the associated space in the + file system is made available for subsequent use. -**EXIT STATUS:** + If the filename specified was the last link to a file but there are open + file descriptor references to it, then the file will remain in existence + until the last file descriptor referencing it is closed. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + None. -None. +EXAMPLES: + The following is an example of how to use ``rm``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``rm``: - -.. code-block:: shell - - SHLL [/] # cp /etc/passwd tmpfile - SHLL [/] # cat tmpfile - root:*:0:0:root::/:/bin/sh - rtems:*:1:1:RTEMS Application::/:/bin/sh - tty:!:2:2:tty owner::/:/bin/false - SHLL [/] # rm tmpfile - SHLL [/] # cat tmpfile - cat: tmpfile: No such file or directory - -**CONFIGURATION:** + SHLL [/] # cp /etc/passwd tmpfile + SHLL [/] # cat tmpfile + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false + SHLL [/] # rm tmpfile + SHLL [/] # cat tmpfile + cat: tmpfile: No such file or directory .. index:: CONFIGURE_SHELL_NO_COMMAND_RM .. index:: CONFIGURE_SHELL_COMMAND_RM -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_RM`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_RM`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_RM`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_RM`` when all shell commands have been + configured. .. index:: rtems_shell_main_rm -The ``rm`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``rm`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_main_rm( - int argc, - char **argv - ); + int rtems_shell_main_rm( + int argc, + char **argv + ); -The configuration structure for the ``rm`` has the -following prototype: -.. code-block:: c + The configuration structure for the ``rm`` has the + following prototype: + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_RM_Command; + extern rtems_shell_cmd_t rtems_shell_RM_Command; + +.. raw:: latex + + \clearpage .. _umask: @@ -2607,70 +2550,67 @@ umask - set file mode creation mask ----------------------------------- .. index:: umask -**SYNOPSYS:** - -.. code-block:: shell - - umask [new_umask] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command sets the user file creation mask to ``new_umask``. The argument -``new_umask`` may be octal, hexadecimal, or decimal. + umask [new_umask] -**EXIT STATUS:** +DESCRIPTION: + This command sets the user file creation mask to ``new_umask``. The + argument ``new_umask`` may be octal, hexadecimal, or decimal. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + This command does not currently support symbolic mode masks. -This command does not currently support symbolic mode masks. +EXAMPLES: + The following is an example of how to use ``umask``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``umask``: - -.. code-block:: shell - - SHLL [/] $ umask - 022 - SHLL [/] $ umask 0666 - 0666 - SHLL [/] $ umask - 0666 - -**CONFIGURATION:** + SHLL [/] $ umask + 022 + SHLL [/] $ umask 0666 + 0666 + SHLL [/] $ umask + 0666 .. index:: CONFIGURE_SHELL_NO_COMMAND_UMASK .. index:: CONFIGURE_SHELL_COMMAND_UMASK -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_UMASK`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_UMASK`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_UMASK`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_UMASK`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_umask -The ``umask`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``umask`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_umask( - int argc, - char **argv - ); + int rtems_shell_rtems_main_umask( + int argc, + char **argv + ); -The configuration structure for the ``umask`` has the following prototype: + The configuration structure for the ``umask`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_UMASK_Command; + extern rtems_shell_cmd_t rtems_shell_UMASK_Command; + +.. raw:: latex + + \clearpage .. _unmount: @@ -2678,61 +2618,54 @@ unmount - unmount disk ---------------------- .. index:: unmount -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell unmount path -**DESCRIPTION:** - -This command unmounts the device at the specified ``path``. - -**EXIT STATUS:** +DESCRIPTION: + This command unmounts the device at the specified ``path``. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + TBD - Surely there must be some warnings to go here. -TBD - Surely there must be some warnings to go here. +EXAMPLES: + The following is an example of how to use ``unmount``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``unmount``: - -.. code-block:: shell - - EXAMPLE_TBD - -**CONFIGURATION:** + EXAMPLE_TBD .. index:: CONFIGURE_SHELL_NO_COMMAND_UNMOUNT .. index:: CONFIGURE_SHELL_COMMAND_UNMOUNT -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_UNMOUNT`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_UNMOUNT`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_UNMOUNT`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_UNMOUNT`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_unmount -The ``unmount`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``unmount`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_unmount( - int argc, - char **argv - ); + int rtems_shell_rtems_main_unmount( + int argc, + char **argv + ); -The configuration structure for the ``unmount`` has the following prototype: + The configuration structure for the ``unmount`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command; + extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command; diff --git a/shell/general_commands.rst b/shell/general_commands.rst index 88d8324..7b0ad5c 100644 --- a/shell/general_commands.rst +++ b/shell/general_commands.rst @@ -55,84 +55,86 @@ This section details the General 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 + .. _help: help - Print command help ------------------------- .. index:: help -**SYNOPSYS:** - -.. code-block:: shell - - help misc - -**DESCRIPTION:** - -This command prints the command help. Help without arguments prints a list of -topics and help with a topic prints the help for that topic. - -**EXIT STATUS:** - -This command returns 0. - -**NOTES:** - -The help print will break the output up based on the environment variable -SHELL_LINES. If this environment variable is not set the default is 16 -lines. If set the number of lines is set to that the value. If the shell lines -is set 0 there will be no break. - -**EXAMPLES:** - -The following is an example of how to use ``alias``: - -.. code-block:: shell - - SHLL [/] $ help - help: ('r' repeat last cmd - 'e' edit last cmd) - TOPIC? The topics are - mem, misc, files, help, rtems, network, monitor - SHLL [/] $ help misc - help: list for the topic 'misc' - alias - alias old new - time - time command [arguments...] - joel - joel [args] SCRIPT - date - date [YYYY-MM-DD HH:MM:SS] - echo - echo [args] - sleep - sleep seconds [nanoseconds] - id - show uid, gid, euid, and egid - tty - show ttyname - whoami - show current user - logoff - logoff from the system - setenv - setenv [var] [string] - getenv - getenv [var] - unsetenv - unsetenv [var] - umask - umask [new_umask] - Press any key to continue... - rtc - real time clock read and set - SHLL [/] $ setenv SHELL_ENV 0 - SHLL [/] $ help misc - help: list for the topic 'misc' - alias - alias old new - time - time command [arguments...] - joel - joel [args] SCRIPT - date - date [YYYY-MM-DD HH:MM:SS] - echo - echo [args] - sleep - sleep seconds [nanoseconds] - id - show uid, gid, euid, and egid - tty - show ttyname - whoami - show current user - logoff - logoff from the system - setenv - setenv [var] [string] - getenv - getenv [var] - unsetenv - unsetenv [var] - umask - umask [new_umask] - rtc - real time clock read and set - -**CONFIGURATION:** - -This command has no configuration. +SYNOPSYS: + .. code-block:: shell + + help misc + +DESCRIPTION: + This command prints the command help. Help without arguments prints a list + of topics and help with a topic prints the help for that topic. + +EXIT STATUS: + This command returns 0. + +NOTES: + The help print will break the output up based on the environment variable + SHELL_LINES. If this environment variable is not set the default is 16 + lines. If set the number of lines is set to that the value. If the shell + lines is set 0 there will be no break. + +EXAMPLES: + The following is an example of how to use ``alias``: + + .. code-block:: shell + + SHLL [/] $ help + help: ('r' repeat last cmd - 'e' edit last cmd) + TOPIC? The topics are + mem, misc, files, help, rtems, network, monitor + SHLL [/] $ help misc + help: list for the topic 'misc' + alias - alias old new + time - time command [arguments...] + joel - joel [args] SCRIPT + date - date [YYYY-MM-DD HH:MM:SS] + echo - echo [args] + sleep - sleep seconds [nanoseconds] + id - show uid, gid, euid, and egid + tty - show ttyname + whoami - show current user + logoff - logoff from the system + setenv - setenv [var] [string] + getenv - getenv [var] + unsetenv - unsetenv [var] + umask - umask [new_umask] + Press any key to continue... + rtc - real time clock read and set + SHLL [/] $ setenv SHELL_ENV 0 + SHLL [/] $ help misc + help: list for the topic 'misc' + alias - alias old new + time - time command [arguments...] + joel - joel [args] SCRIPT + date - date [YYYY-MM-DD HH:MM:SS] + echo - echo [args] + sleep - sleep seconds [nanoseconds] + id - show uid, gid, euid, and egid + tty - show ttyname + whoami - show current user + logoff - logoff from the system + setenv - setenv [var] [string] + getenv - getenv [var] + unsetenv - unsetenv [var] + umask - umask [new_umask] + rtc - real time clock read and set + +CONFIGURATION: + This command has no configuration. + +.. raw:: latex + + \clearpage .. _alias: @@ -140,70 +142,68 @@ alias - add alias for an existing command ----------------------------------------- .. index:: alias -**SYNOPSYS:** - -.. code-block:: shell - - alias oldCommand newCommand - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command adds an alternate name for an existing command to the command set. + alias oldCommand newCommand -**EXIT STATUS:** +DESCRIPTION: + This command adds an alternate name for an existing command to the command + set. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + None. -None. +EXAMPLES: + The following is an example of how to use ``alias``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``alias``: - -.. code-block:: shell - - SHLL [/] $ me - shell:me command not found - SHLL [/] $ alias whoami me - SHLL [/] $ me - rtems - SHLL [/] $ whoami - rtems - -**CONFIGURATION:** + SHLL [/] $ me + shell:me command not found + SHLL [/] $ alias whoami me + SHLL [/] $ me + rtems + SHLL [/] $ whoami + rtems .. index:: CONFIGURE_SHELL_NO_COMMAND_ALIAS .. index:: CONFIGURE_SHELL_COMMAND_ALIAS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_ALIAS`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ALIAS`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_ALIAS`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ALIAS`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_alias -The ``alias`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``alias`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_alias( - int argc, - char **argv - ); + int rtems_shell_rtems_main_alias( + int argc, + char **argv + ); -The configuration structure for the ``alias`` has the following prototype: + The configuration structure for the ``alias`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_ALIAS_Command; + extern rtems_shell_cmd_t rtems_shell_ALIAS_Command; + +.. raw:: latex + + \clearpage .. _cmdls: @@ -211,54 +211,51 @@ cmdls - List commands --------------------- .. index:: cmdls -**SYNOPSYS:** - -.. code-block:: shell - - cmdls COMMAND... - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command lists the visible commands of the command set. + cmdls COMMAND... -**EXIT STATUS:** +DESCRIPTION: + This command lists the visible commands of the command set. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + The current user must have read permission to list a command. -The current user must have read permission to list a command. +EXAMPLES: + The following is an example of how to use ``cmdls``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``cmdls``: - -.. code-block:: shell - - SHLL [/] # cmdls help shutdown - r-xr-xr-x 0 0 help - r-x------ 0 0 shutdown - -**CONFIGURATION:** + SHLL [/] # cmdls help shutdown + r-xr-xr-x 0 0 help + r-x------ 0 0 shutdown .. index:: CONFIGURE_SHELL_NO_COMMAND_CMDLS .. index:: CONFIGURE_SHELL_COMMAND_CMDLS -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDLS`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDLS`` to have this + command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CMDLS`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CMDLS`` when all shell commands have been -configured. +PROGRAMMING INFORMATION: + The configuration structure for the ``cmdls`` has the following prototype: -**PROGRAMMING INFORMATION:** + .. code-block:: c -The configuration structure for the ``cmdls`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_CMDLS_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_CMDLS_Command; + \clearpage .. _cmdchown: @@ -266,57 +263,55 @@ cmdchown - Change user or owner of commands ------------------------------------------- .. index:: cmdchown -**SYNOPSYS:** +SYNOPSYS: + .. code-block:: shell -.. code-block:: shell + cmdchown [OWNER][:[GROUP]] COMMAND... - cmdchown [OWNER][:[GROUP]] COMMAND... +DESCRIPTION: + This command changes the user or owner of a command. -**DESCRIPTION:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command changes the user or owner of a command. +NOTES: + The current user must have an UID of zero or be the command owner to change + the owner or group. -**EXIT STATUS:** +EXAMPLES: + The following is an example of how to use ``cmdchown``: -This command returns 0 on success and non-zero if an error is encountered. + .. code-block:: shell -**NOTES:** - -The current user must have an UID of zero or be the command owner to change the -owner or group. - -**EXAMPLES:** - -The following is an example of how to use ``cmdchown``: - -.. code-block:: shell - - [/] # cmdls help - r-xr-xr-x 0 0 help - [/] # cmdchown 1:1 help - [/] # cmdls help - r--r--r-- 1 1 help - -**CONFIGURATION:** + [/] # cmdls help + r-xr-xr-x 0 0 help + [/] # cmdchown 1:1 help + [/] # cmdls help + r--r--r-- 1 1 help .. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN .. index:: CONFIGURE_SHELL_COMMAND_CMDCHOWN -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDCHOWN`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDCHOWN`` to have + this command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN`` when all shell commands have been -configured. +PROGRAMMING INFORMATION: + The configuration structure for the ``cmdchown`` has the following + prototype: -**PROGRAMMING INFORMATION:** + .. code-block:: c -The configuration structure for the ``cmdchown`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command; + \clearpage .. _cmdchmod: @@ -324,57 +319,55 @@ cmdchmod - Change mode of commands ---------------------------------- .. index:: cmdchmod -**SYNOPSYS:** - -.. code-block:: shell - - cmdchmod OCTAL-MODE COMMAND... +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + cmdchmod OCTAL-MODE COMMAND... -This command changes the mode of a command. +DESCRIPTION: + This command changes the mode of a command. -**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: + The current user must have an UID of zero or be the command owner to change + the mode. -**NOTES:** +EXAMPLES: + The following is an example of how to use ``cmdchmod``: -The current user must have an UID of zero or be the command owner to change the -mode. + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``cmdchmod``: - -.. code-block:: shell - - [/] # cmdls help - r-xr-xr-x 0 0 help - [/] # cmdchmod 544 help - [/] # cmdls help - r-xr--r-- 0 0 help - -**CONFIGURATION:** + [/] # cmdls help + r-xr-xr-x 0 0 help + [/] # cmdchmod 544 help + [/] # cmdls help + r-xr--r-- 0 0 help .. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD .. index:: CONFIGURE_SHELL_COMMAND_CMDCHMOD -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDCHMOD`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CMDCHMOD`` to have + this command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD`` when all shell commands have been -configured. +PROGRAMMING INFORMATION: + The configuration structure for the ``cmdchmod`` has the following + prototype: -**PROGRAMMING INFORMATION:** + .. code-block:: c -The configuration structure for the ``cmdchmod`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command; + \clearpage .. _date: @@ -382,74 +375,71 @@ date - print or set current date and time ----------------------------------------- .. index:: date -**SYNOPSYS:** - -.. code-block:: shell - - date - date DATE TIME - -**DESCRIPTION:** - -This command operates one of two modes. When invoked with no arguments, it -prints the current date and time. When invoked with both ``date`` and ``time`` -arguments, it sets the current time. +SYNOPSYS: + .. code-block:: shell -The ``date`` is specified in ``YYYY-MM-DD`` format. -The ``time`` is specified in ``HH:MM:SS`` format. + date + date DATE TIME -**EXIT STATUS:** +DESCRIPTION: + This command operates one of two modes. When invoked with no arguments, it + prints the current date and time. When invoked with both ``date`` and + ``time`` arguments, it sets the current time. -This command returns 0 on success and non-zero if an error is encountered. + The ``date`` is specified in ``YYYY-MM-DD`` format. + The ``time`` is specified in ``HH:MM:SS`` format. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -None. +NOTES: + None. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``date``: -The following is an example of how to use ``date``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ date - Fri Jan 1 00:00:09 1988 - SHLL [/] $ date 2008-02-29 06:45:32 - SHLL [/] $ date - Fri Feb 29 06:45:35 2008 - -**CONFIGURATION:** + SHLL [/] $ date + Fri Jan 1 00:00:09 1988 + SHLL [/] $ date 2008-02-29 06:45:32 + SHLL [/] $ date + Fri Feb 29 06:45:35 2008 .. index:: CONFIGURE_SHELL_NO_COMMAND_DATE .. index:: CONFIGURE_SHELL_COMMAND_DATE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DATE`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DATE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DATE`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DATE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_date -The ``date`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``date`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_date( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``date`` has the following prototype: - int rtems_shell_rtems_main_date( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``date`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_DATE_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_DATE_Command; + \clearpage .. _echo: @@ -457,113 +447,110 @@ echo - produce message in a shell script ---------------------------------------- .. index:: echo -**SYNOPSYS:** - -.. code-block:: shell - - echo [-n | -e] args ... - -**DESCRIPTION:** - -Echo prints its arguments on the standard output, separated by spaces. Unless -the *-n* option is present, a newline is output following the arguments. The -*-e* option causes echo to treat the escape sequences specially, as described -in the following paragraph. The *-e* option is the default, and is provided -solely for compatibility with other systems. Only one of the options *-n* and -*-e* may be given. +SYNOPSYS: + .. code-block:: shell -If any of the following sequences of characters is encountered during output, -the sequence is not output. Instead, the specified action is performed: + echo [-n | -e] args ... -*\b* - A backspace character is output. +DESCRIPTION: + Echo prints its arguments on the standard output, separated by spaces. + Unless the *-n* option is present, a newline is output following the + arguments. The *-e* option causes echo to treat the escape sequences + specially, as described in the following paragraph. The *-e* option is the + default, and is provided solely for compatibility with other systems. Only + one of the options *-n* and *-e* may be given. -*\c* - Subsequent output is suppressed. This is normally used at the end of the - last argument to suppress the trailing newline that echo would otherwise - output. + If any of the following sequences of characters is encountered during + output, the sequence is not output. Instead, the specified action is + performed: -*\f* - Output a form feed. + *\b* + A backspace character is output. -*\n* - Output a newline character. + *\c* + Subsequent output is suppressed. This is normally used at the end of + the last argument to suppress the trailing newline that echo would + otherwise output. -*\r* - Output a carriage return. + *\f* + Output a form feed. -*\t* - Output a (horizontal) tab character. + *\n* + Output a newline character. -*\v* - Output a vertical tab. + *\r* + Output a carriage return. -*\0digits* - Output the character whose value is given by zero to three digits. If - there are zero digits, a nul character is output. + *\t* + Output a (horizontal) tab character. -*\\* - Output a backslash. + *\v* + Output a vertical tab. -**EXIT STATUS:** + *\0digits* + Output the character whose value is given by zero to three digits. If + there are zero digits, a nul character is output. -This command returns 0 on success and non-zero if an error is encountered. + *\\* + Output a backslash. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The octal character escape mechanism (\0digits) differs from the C language -mechanism. +NOTES: + The octal character escape mechanism (\0digits) differs from the C language + mechanism. -There is no way to force ``echo`` to treat its arguments literally, rather than -interpreting them as options and escape sequences. + There is no way to force ``echo`` to treat its arguments literally, rather + than interpreting them as options and escape sequences. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``echo``: -The following is an example of how to use ``echo``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ echo a b c - a b c - SHLL [/] $ echo - -**CONFIGURATION:** + SHLL [/] $ echo a b c + a b c + SHLL [/] $ echo .. index:: CONFIGURE_SHELL_NO_COMMAND_ECHO .. index:: CONFIGURE_SHELL_COMMAND_ECHO -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_ECHO`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ECHO`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_ECHO`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ECHO`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_echo -The ``echo`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``echo`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_echo( - int argc, - char **argv - ); + int rtems_shell_rtems_main_echo( + int argc, + char **argv + ); -The configuration structure for the ``echo`` has the following prototype: + The configuration structure for the ``echo`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_ECHO_Command; + extern rtems_shell_cmd_t rtems_shell_ECHO_Command; -**ORIGIN:** +ORIGIN: + The implementation and portions of the documentation for this command are + from NetBSD 4.0. -The implementation and portions of the documentation for this command are from -NetBSD 4.0. +.. raw:: latex + + \clearpage .. _sleep: @@ -571,76 +558,74 @@ sleep - delay for a specified amount of time -------------------------------------------- .. index:: sleep -**SYNOPSYS:** - -.. code-block:: shell - - sleep seconds - sleep seconds nanoseconds - -**DESCRIPTION:** - -This command causes the task executing the shell to block for the specified -number of ``seconds`` and ``nanoseconds``. - -**EXIT STATUS:** +SYNOPSYS: + .. code-block:: shell -This command returns 0 on success and non-zero if an error is encountered. + sleep seconds + sleep seconds nanoseconds -**NOTES:** +DESCRIPTION: + This command causes the task executing the shell to block for the specified + number of ``seconds`` and ``nanoseconds``. -This command is implemented using the ``nanosleep()`` method. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The command line interface is similar to the ``sleep`` command found on POSIX -systems but the addition of the ``nanoseconds`` parameter allows fine grained -delays in shell scripts without adding another command such as ``usleep``. +NOTES: + This command is implemented using the ``nanosleep()`` method. -**EXAMPLES:** + The command line interface is similar to the ``sleep`` command found on + POSIX systems but the addition of the ``nanoseconds`` parameter allows fine + grained delays in shell scripts without adding another command such as + ``usleep``. -The following is an example of how to use ``sleep``: +EXAMPLES: + The following is an example of how to use ``sleep``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ sleep 10 - SHLL [/] $ sleep 0 5000000 + SHLL [/] $ sleep 10 + SHLL [/] $ sleep 0 5000000 -It is not clear from the above but there is a ten second pause after executing -the first command before the prompt is printed. The second command completes -very quickly from a human perspective and there is no noticeable delay in the -prompt being printed. - -**CONFIGURATION:** + It is not clear from the above but there is a ten second pause after + executing the first command before the prompt is printed. The second + command completes very quickly from a human perspective and there is no + noticeable delay in the prompt being printed. .. index:: CONFIGURE_SHELL_NO_COMMAND_SLEEP .. index:: CONFIGURE_SHELL_COMMAND_SLEEP -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_SLEEP`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_SLEEP`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_SLEEP`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_SLEEP`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_sleep -The ``sleep`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``sleep`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_sleep( + int argc, + char **argv + ); - int rtems_shell_rtems_main_sleep( - int argc, - char **argv - ); + The configuration structure for the ``sleep`` has the following prototype: -The configuration structure for the ``sleep`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_SLEEP_Command; - extern rtems_shell_cmd_t rtems_shell_SLEEP_Command; +.. raw:: latex + + \clearpage .. _id: @@ -648,76 +633,73 @@ id - show uid gid euid and egid ------------------------------- .. index:: id -**SYNOPSYS:** - -.. code-block:: shell - - id - -**DESCRIPTION:** - -This command prints the user identity. This includes the user id (uid), group -id (gid), effective user id (euid), and effective group id (egid). - -**EXIT STATUS:** +SYNOPSYS: + .. code-block:: shell -This command returns 0 on success and non-zero if an error is encountered. + id -**NOTES:** +DESCRIPTION: + This command prints the user identity. This includes the user id (uid), + group id (gid), effective user id (euid), and effective group id (egid). -Remember there is only one POSIX process in a single processor RTEMS -application. Each thread may have its own user identity and that identity is -used by the filesystem to enforce permissions. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + Remember there is only one POSIX process in a single processor RTEMS + application. Each thread may have its own user identity and that identity + is used by the filesystem to enforce permissions. -The first example of the ``id`` command is from a session logged -in as the normal user ``rtems``: +EXAMPLES: + The first example of the ``id`` command is from a session logged + in as the normal user ``rtems``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] # id - uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems) + SHLL [/] # id + uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems) -The second example of the ``id`` command is from a session logged in as the -``root`` user: + The second example of the ``id`` command is from a session logged in as the + ``root`` user: -.. code-block:: shell + .. code-block:: shell - SHLL [/] # id - uid=0(root),gid=0(root),euid=0(root),egid=0(root) - -**CONFIGURATION:** + SHLL [/] # id + uid=0(root),gid=0(root),euid=0(root),egid=0(root) .. index:: CONFIGURE_SHELL_NO_COMMAND_ID .. index:: CONFIGURE_SHELL_COMMAND_ID -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_ID`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ID`` when all shell commands have been configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_ID`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ID`` when all shell commands have been configured. .. index:: rtems_shell_rtems_main_id -The ``id`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``id`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_id( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``id`` has the following prototype: - int rtems_shell_rtems_main_id( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``id`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_ID_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_ID_Command; + \clearpage .. _tty: @@ -725,65 +707,63 @@ tty - show ttyname ------------------ .. index:: tty -**SYNOPSYS:** - -.. code-block:: shell - - tty - -**DESCRIPTION:** - -This command prints the file name of the device connected to standard input. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + tty -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + This command prints the file name of the device connected to standard + input. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -NONE +NOTES: + NONE -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``tty``: -The following is an example of how to use ``tty``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ tty - /dev/console - -**CONFIGURATION:** + SHLL [/] $ tty + /dev/console .. index:: CONFIGURE_SHELL_NO_COMMAND_TTY .. index:: CONFIGURE_SHELL_COMMAND_TTY -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_TTY`` to have this command -included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_TTY`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_TTY`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_TTY`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_tty -The ``tty`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``tty`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_tty( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``tty`` has the following prototype: - int rtems_shell_rtems_main_tty( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``tty`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_TTY_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_TTY_Command; + \clearpage .. _whoami: @@ -791,66 +771,64 @@ whoami - print effective user id -------------------------------- .. index:: whoami -**SYNOPSYS:** - -.. code-block:: shell - - whoami - -**DESCRIPTION:** - -This command displays the user name associated with the current effective user -id. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + whoami -This command always succeeds. +DESCRIPTION: + This command displays the user name associated with the current effective + user + id. -**NOTES:** +EXIT STATUS: + This command always succeeds. -None. +NOTES: + None. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``whoami``: -The following is an example of how to use ``whoami``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ whoami - rtems - -**CONFIGURATION:** + SHLL [/] $ whoami + rtems .. index:: CONFIGURE_SHELL_NO_COMMAND_WHOAMI .. index:: CONFIGURE_SHELL_COMMAND_WHOAMI -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_WHOAMI`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_WHOAMI`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_WHOAMI`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_WHOAMI`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_whoami -The ``whoami`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``whoami`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_whoami( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``whoami`` has the following prototype: - int rtems_shell_rtems_main_whoami( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``whoami`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command; + \clearpage .. _getenv: @@ -858,66 +836,64 @@ getenv - print environment variable ----------------------------------- .. index:: getenv -**SYNOPSYS:** - -.. code-block:: shell - - getenv variable - -**DESCRIPTION:** - -This command is used to display the value of a ``variable`` in the set of -environment variables. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + getenv variable -This command will return 1 and print a diagnostic message if a failure occurs. +DESCRIPTION: + This command is used to display the value of a ``variable`` in the set of + environment variables. -**NOTES:** +EXIT STATUS: + This command will return 1 and print a diagnostic message if a failure + occurs. -The entire RTEMS application shares a single set of environment variables. +NOTES: + The entire RTEMS application shares a single set of environment variables. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``getenv``: -The following is an example of how to use ``getenv``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ getenv BASEPATH - /mnt/hda1 - -**CONFIGURATION:** + SHLL [/] $ getenv BASEPATH + /mnt/hda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_GETENV .. index:: CONFIGURE_SHELL_COMMAND_GETENV -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_GETENV`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_GETENV`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_GETENV`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_GETENV`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_getenv -The ``getenv`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``getenv`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_getenv( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``getenv`` has the following prototype: - int rtems_shell_rtems_main_getenv( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``getenv`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_GETENV_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_GETENV_Command; + \clearpage .. _setenv: @@ -925,67 +901,65 @@ setenv - set environment variable --------------------------------- .. index:: setenv -**SYNOPSYS:** - -.. code-block:: shell - - setenv variable [value] - -**DESCRIPTION:** - -This command is used to add a new ``variable`` to the set of environment -variables or to modify the variable of an already existing ``variable``. If -the ``value`` is not provided, the ``variable`` will be set to the empty -string. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + setenv variable [value] -This command will return 1 and print a diagnostic message if a failure occurs. +DESCRIPTION: + This command is used to add a new ``variable`` to the set of environment + variables or to modify the variable of an already existing ``variable``. + If the ``value`` is not provided, the ``variable`` will be set to the empty + string. -**NOTES:** +EXIT STATUS: + This command will return 1 and print a diagnostic message if a failure + occurs. -The entire RTEMS application shares a single set of environment variables. +NOTES: + The entire RTEMS application shares a single set of environment variables. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``setenv``: -The following is an example of how to use ``setenv``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ setenv BASEPATH /mnt/hda1 - -**CONFIGURATION:** + SHLL [/] $ setenv BASEPATH /mnt/hda1 .. index:: CONFIGURE_SHELL_NO_COMMAND_SETENV .. index:: CONFIGURE_SHELL_COMMAND_SETENV -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_SETENV`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_SETENV`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_SETENV`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_SETENV`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_setenv -The ``setenv`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``setenv`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_setenv( + int argc, + char **argv + ); - int rtems_shell_rtems_main_setenv( - int argc, - char **argv - ); + The configuration structure for the ``setenv`` has the following prototype: -The configuration structure for the ``setenv`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_SETENV_Command; - extern rtems_shell_cmd_t rtems_shell_SETENV_Command; +.. raw:: latex + + \clearpage .. _unsetenv: @@ -993,64 +967,63 @@ unsetenv - unset environment variable ------------------------------------- .. index:: unsetenv -**SYNOPSYS:** - -.. code-block:: shell - - unsetenv variable - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command is remove to a ``variable`` from the set of environment variables. + unsetenv variable -**EXIT STATUS:** +DESCRIPTION: + This command is remove to a ``variable`` from the set of environment + variables. -This command will return 1 and print a diagnostic message if a failure occurs. +EXIT STATUS: + This command will return 1 and print a diagnostic message if a failure + occurs. -**NOTES:** +NOTES: + The entire RTEMS application shares a single set of environment variables. -The entire RTEMS application shares a single set of environment variables. +EXAMPLES: + The following is an example of how to use ``unsetenv``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``unsetenv``: - -.. code-block:: shell - - SHLL [/] $ unsetenv BASEPATH - -**CONFIGURATION:** + SHLL [/] $ unsetenv BASEPATH .. index:: CONFIGURE_SHELL_NO_COMMAND_UNSETENV .. index:: CONFIGURE_SHELL_COMMAND_UNSETENV -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_UNSETENV`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_UNSETENV`` to have + this command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_UNSETENV`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_UNSETENV`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_unsetenv -The ``unsetenv`` is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``unsetenv`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_unsetenv( + int argc, + char **argv + ); - int rtems_shell_rtems_main_unsetenv( - int argc, - char **argv - ); + The configuration structure for the ``unsetenv`` has the following prototype: -The configuration structure for the ``unsetenv`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command; - extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command; +.. raw:: latex + + \clearpage .. _time: @@ -1058,65 +1031,62 @@ time - time command execution ----------------------------- .. index:: time -**SYNOPSYS:** - -.. code-block:: c - - time command [argument ...] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: c -The time command executes and times a command. After the command finishes, -time writes the total time elapsed. Times are reported in seconds. + time command [argument ...] -**EXIT STATUS:** +DESCRIPTION: + The time command executes and times a command. After the command finishes, + time writes the total time elapsed. Times are reported in seconds. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + None. -None. +EXAMPLES: + The following is an example of how to use ``time``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``time``: - -.. code-block:: shell - - SHLL [/] $ time cp -r /nfs/directory /c - -**CONFIGURATION:** + SHLL [/] $ time cp -r /nfs/directory /c .. index:: CONFIGURE_SHELL_NO_COMMAND_TIME .. index:: CONFIGURE_SHELL_COMMAND_TIME -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_TIME`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_TIME`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_TIME`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_TIME`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_time -The ``time`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``time`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_time( + int argc, + char **argv + ); - int rtems_shell_rtems_main_time( - int argc, - char **argv - ); + The configuration structure for the ``time`` has the following prototype: -The configuration structure for the ``time`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_TIME_Command; - extern rtems_shell_cmd_t rtems_shell_TIME_Command; +.. raw:: latex + + \clearpage .. _logoff: @@ -1124,68 +1094,65 @@ logoff - logoff from the system ------------------------------- .. index:: logoff -**SYNOPSYS:** - -.. code-block:: shell - - logoff - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command logs the user out of the shell. + logoff -**EXIT STATUS:** +DESCRIPTION: + This command logs the user out of the shell. -This command does not return. +EXIT STATUS: + This command does not return. -**NOTES:** +NOTES: + The system behavior when the shell is exited depends upon how the shell was + initiated. The typical behavior is that a login prompt will be displayed + for the next login attempt or that the connection will be dropped by the + RTEMS system. -The system behavior when the shell is exited depends upon how the shell was -initiated. The typical behavior is that a login prompt will be displayed for -the next login attempt or that the connection will be dropped by the RTEMS -system. +EXAMPLES: + The following is an example of how to use ``logoff``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``logoff``: - -.. code-block:: shell - - SHLL [/] $ logoff - logoff from the system... - -**CONFIGURATION:** + SHLL [/] $ logoff + logoff from the system... .. index:: CONFIGURE_SHELL_NO_COMMAND_LOGOFF .. index:: CONFIGURE_SHELL_COMMAND_LOGOFF -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_LOGOFF`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_LOGOFF`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_LOGOFF`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_LOGOFF`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_logoff -The ``logoff`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``logoff`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_logoff( + int argc, + char **argv + ); - int rtems_shell_rtems_main_logoff( - int argc, - char **argv - ); + The configuration structure for the ``logoff`` has the following prototype: -The configuration structure for the ``logoff`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command; - extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command; +.. raw:: latex + + \clearpage .. _rtc: @@ -1193,24 +1160,26 @@ rtc - RTC driver configuration ------------------------------ .. index:: rtc -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - rtc - -**CONFIGURATION:** + rtc .. index:: CONFIGURE_SHELL_NO_COMMAND_RTC .. index:: CONFIGURE_SHELL_COMMAND_RTC -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_RTC`` to have this command -included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_RTC`` to have this + command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all shell commands have been -configured. +.. raw:: latex + + \clearpage .. _exit: @@ -1218,39 +1187,32 @@ exit - exit the shell --------------------- .. index:: exit -**SYNOPSYS:** - -.. code-block:: shell - - exit - -**DESCRIPTION:** - -This command causes the shell interpreter to ``exit``. - -**EXIT STATUS:** - -This command does not return. - -**NOTES:** +SYNOPSYS: + .. code-block:: shell -In contrast to `logoff - logoff from the system`, this command is built into -the shell interpreter loop. + exit -**EXAMPLES:** +DESCRIPTION: + This command causes the shell interpreter to ``exit``. -The following is an example of how to use ``exit``: +EXIT STATUS: + This command does not return. -.. code-block:: shell +NOTES: + In contrast to `logoff - logoff from the system`, this command is built + into the shell interpreter loop. - SHLL [/] $ exit - Shell exiting +EXAMPLES: + The following is an example of how to use ``exit``: -**CONFIGURATION:** + .. code-block:: shell -This command is always present and cannot be disabled. + SHLL [/] $ exit + Shell exiting -**PROGRAMMING INFORMATION:** +CONFIGURATION: + This command is always present and cannot be disabled. -The ``exit`` is implemented directly in the shell interpreter. There is no C -routine associated with it. +PROGRAMMING INFORMATION: + The ``exit`` is implemented directly in the shell interpreter. There is no + C routine associated with it. diff --git a/shell/index.rst b/shell/index.rst index 9fdfdce..7074078 100644 --- a/shell/index.rst +++ b/shell/index.rst @@ -39,7 +39,7 @@ to the Community Project hosted at http://www.rtems.org/. ================ ============================= .. toctree:: - :maxdepth: 3 + :maxdepth: 4 :numbered: preface diff --git a/shell/memory_commands.rst b/shell/memory_commands.rst index ff0a4bf..ece85ff 100644 --- a/shell/memory_commands.rst +++ b/shell/memory_commands.rst @@ -34,89 +34,90 @@ 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:** - -.. 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. - -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. +SYNOPSYS: + .. code-block:: shell -When ``address`` is not provided, it defaults to ``0x00000000``. + mdump [address [length [size]]] -**EXIT STATUS:** +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in ``size`` byte units specified on the command line. -This command always returns 0 to indicate success. + 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. -**NOTES:** + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with sixteen bytes of output per line. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. + When ``address`` is not provided, it defaults to ``0x00000000``. -**EXAMPLES:** +EXIT STATUS: + This command always returns 0 to indicate success. -The following is an example of how to use ``mdump``: +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``mdump``: - SHLL [/] $ mdump 0x10000 32 - 0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ - 0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ - SHLL [/] $ mdump 0x02000000 32 - 0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. - 0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!. - SHLL [/] $ mdump 0x02001000 32 - 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 ..`....... ..(.. + .. code-block:: shell -**CONFIGURATION:** + SHLL [/] $ mdump 0x10000 32 + 0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ + 0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ + SHLL [/] $ mdump 0x02000000 32 + 0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. + 0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!. + SHLL [/] $ mdump 0x02001000 32 + 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 ..`....... ..(.. .. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP .. index:: CONFIGURE_SHELL_COMMAND_MDUMP -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. +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. -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:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all shell commands have been + configured. .. 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 -.. code-block:: c + int rtems_shell_rtems_main_mdump( + int argc, + char **argv + ); - int rtems_shell_rtems_main_mdump( - int argc, - char **argv - ); + The configuration structure for the ``mdump`` has the following prototype: -The configuration structure for the ``mdump`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; - extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; +.. raw:: latex + + \clearpage .. _wdump: @@ -124,75 +125,72 @@ wdump - display contents of memory (word) ----------------------------------------- .. index:: wdump -**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. - -This command is equivalent to ``mdump address length 2``. +SYNOPSYS: + .. code-block:: shell -When ``length`` is not provided, it defaults to ``320`` which is twenty lines -of output with eight words of output per line. + wdump [address [length]] -When ``address`` is not provided, it defaults to ``0x00000000``. +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in bytes specified on the command line. -**EXIT STATUS:** + This command is equivalent to ``mdump address length 2``. -This command always returns 0 to indicate success. + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with eight words of output per line. -**NOTES:** + When ``address`` is not provided, it defaults to ``0x00000000``. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +EXIT STATUS: + This command always returns 0 to indicate success. -**EXAMPLES:** +NOTES: + Dumping memory from a non-existent address may result in an unrecoverable + program fault. -The following is an example of how to use ``wdump``: +EXAMPLES: + The following is an example of how to use ``wdump``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ wdump 0x02010000 32 - 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t - 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... - -**CONFIGURATION:** + SHLL [/] $ wdump 0x02010000 32 + 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t + 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... .. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP .. index:: CONFIGURE_SHELL_COMMAND_WDUMP -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all shell commands have been + configured. .. 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 + + int rtems_shell_rtems_main_wdump( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``wdump`` has the following prototype: - int rtems_shell_rtems_main_wdump( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``wdump`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; + \clearpage .. _ldump: @@ -200,75 +198,72 @@ ldump - display contents of memory (longword) --------------------------------------------- .. index:: ldump -**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. +SYNOPSYS: + .. code-block:: shell -This command is equivalent to ``mdump address length 4``. + ldump [address [length]] -When ``length`` is not provided, it defaults to ``320`` which is twenty lines -of output with four longwords of output per line. +DESCRIPTION: + This command displays the contents of memory at the ``address`` and + ``length`` in bytes specified on the command line. -When ``address`` is not provided, it defaults to ``0x00000000``. + This command is equivalent to ``mdump address length 4``. -**EXIT STATUS:** + When ``length`` is not provided, it defaults to ``320`` which is twenty + lines of output with four longwords of output per line. -This command always returns 0 to indicate success. + When ``address`` is not provided, it defaults to ``0x00000000``. -**NOTES:** +EXIT STATUS: + This command always returns 0 to indicate success. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +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``: -The following is an example of how to use ``ldump``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ ldump 0x02010000 32 - 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t - 0x02010010 020 0894 02010718-02010640 02010798 ............... - -**CONFIGURATION:** + SHLL [/] $ ldump 0x02010000 32 + 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t + 0x02010010 020 0894 02010718-02010640 02010798 ............... .. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP .. index:: CONFIGURE_SHELL_COMMAND_LDUMP -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. +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. -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:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ldump -The ``ldump`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``ldump`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_ldump( + int argc, + char **argv + ); - int rtems_shell_rtems_main_ldump( - int argc, - char **argv - ); + The configuration structure for the ``ldump`` has the following prototype: -The configuration structure for the ``ldump`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; - extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; +.. raw:: latex + + \clearpage .. _medit: @@ -276,73 +271,70 @@ medit - modify contents of memory --------------------------------- .. index:: medit -**SYNOPSYS:** - -.. code-block:: shell - - medit address value1 [value2 ... valueN] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command is used to modify the contents of the memory starting at -``address`` using the octets specified by the parameters``value1`` through -``valueN``. + medit address value1 [value2 ... valueN] -**EXIT STATUS:** +DESCRIPTION: + This command is used to modify the contents of the memory starting at + ``address`` using the octets specified by the parameters``value1`` through + ``valueN``. -This command returns 0 on success and non-zero if an error is encountered. +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. -Dumping memory from a non-existent address may result in an unrecoverable -program fault. +EXAMPLES: + The following is an example of how to use ``medit``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``medit``: - -.. code-block:: shell - - SHLL [/] $ mdump 0x02000000 32 - 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. - 0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!. - SHLL [/] $ medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 - SHLL [/] $ mdump 0x02000000 32 - 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:** + SHLL [/] $ mdump 0x02000000 32 + 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. + 0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!. + SHLL [/] $ medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 + SHLL [/] $ mdump 0x02000000 32 + 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.."...!. .. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT .. index:: CONFIGURE_SHELL_COMMAND_MEDIT -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all shell commands have been + configured. .. 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 + .. code-block:: c - int rtems_shell_rtems_main_medit( - int argc, - char **argv - ); + int rtems_shell_rtems_main_medit( + int argc, + char **argv + ); -The configuration structure for the ``medit`` has the following prototype: + The configuration structure for the ``medit`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + +.. raw:: latex + + \clearpage .. _mfill: @@ -350,80 +342,78 @@ mfill - file memory with pattern -------------------------------- .. index:: mfill -**SYNOPSYS:** - -.. code-block:: shell - - mfill address length value +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + mfill address length value -This command is used to fill the memory starting at ``address`` for the -specified ``length`` in octets when the specified at``value``. +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. -This command returns 0 on success and non-zero if an error is encountered. +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. -**NOTES:** +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. -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. + .. code-block:: shell -**EXAMPLES:** - -In this example, the address used (``0x23d89a0``) as the base address of the -filled area is the end of the stack for the Idle thread. This address was -determined manually using gdb and is very specific to this application and BSP. -The first command in this example is an ``mdump`` to display the initial -contents of this memory. We see that the first 8 bytes are 0xA5 which is the -pattern used as a guard by the Stack Checker. On the first context switch -after the pattern is overwritten by the ``mfill`` command, the Stack Checker -detect the pattern has been corrupted and generates a fatal error. - -.. code-block:: shell - - SHLL [/] $ mdump 0x23d89a0 16 - 0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................ - SHLL [/] $ mfill 0x23d89a0 13 0x5a - SHLL [/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908 - stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes) - Damaged pattern begins at 0x023D89A8 and is 16 bytes long - -**CONFIGURATION:** + SHLL [/] $ mdump 0x23d89a0 16 + 0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................ + SHLL [/] $ mfill 0x23d89a0 13 0x5a + SHLL [/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908 + stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes) + Damaged pattern begins at 0x023D89A8 and is 16 bytes long .. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL .. index:: CONFIGURE_SHELL_COMMAND_MFILL -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. +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. -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:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all shell commands have been + configured. .. 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 -.. code-block:: c + int rtems_shell_rtems_main_mfill( + int argc, + char **argv + ); - int rtems_shell_rtems_main_mfill( - int argc, - char **argv - ); + The configuration structure for the ``mfill`` has the + following prototype: -The configuration structure for the ``mfill`` has the -following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_MFILL_Command; - extern rtems_shell_cmd_t rtems_shell_MFILL_Command; +.. raw:: latex + + \clearpage .. _mmove: @@ -431,71 +421,68 @@ mmove - move contents of memory ------------------------------- .. index:: mmove -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - mmove dst src length + mmove dst src length -**DESCRIPTION:** +DESCRIPTION: + This command is used to copy the contents of the memory starting at ``src`` + to the memory located at ``dst`` for the specified ``length`` in octets. -This command is used to copy the contents of the memory starting at ``src`` to -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. -**EXIT STATUS:** +NOTES: + NONE -This command returns 0 on success and non-zero if an error is encountered. +EXAMPLES: + The following is an example of how to use ``mmove``: -**NOTES:** + .. code-block:: shell -NONE - -**EXAMPLES:** - -The following is an example of how to use ``mmove``: - -.. code-block:: shell - - SHLL [/] $ mdump 0x023d99a0 16 - 0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................ - SHLL [/] $ mdump 0x02000000 16 - 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. - SHLL [/] $ mmove 0x023d99a0 0x02000000 13 - SHLL [/] $ mdump 0x023d99a0 16 - 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3.."..... - -**CONFIGURATION:** + SHLL [/] $ mdump 0x023d99a0 16 + 0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................ + SHLL [/] $ mdump 0x02000000 16 + 0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!. + SHLL [/] $ mmove 0x023d99a0 0x02000000 13 + SHLL [/] $ mdump 0x023d99a0 16 + 0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3.."..... .. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE .. index:: CONFIGURE_SHELL_COMMAND_MMOVE -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all shell commands have been + configured. .. 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 + + int rtems_shell_rtems_main_mmove( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``mmove`` has the following prototype: - int rtems_shell_rtems_main_mmove( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``mmove`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; + \clearpage .. _malloc: @@ -503,137 +490,130 @@ malloc - obtain information on C program heap --------------------------------------------- .. index:: malloc -**SYNOPSYS:** +SYNOPSYS: + .. code-block:: shell -.. code-block:: shell + malloc [walk] - 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:** + - Number of free blocks -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: + - Largest free block -- Number of free blocks + - Total bytes free -- Largest free block + - Number of used blocks -- Total bytes free + - Largest used block -- Number of used blocks + - Total bytes used -- Largest used block + - Size of the allocatable area in bytes -- Total bytes used + - Minimum free size ever in bytes -- Size of the allocatable area in bytes + - Maximum number of free blocks ever -- Minimum free size ever in bytes + - Maximum number of blocks searched ever -- Maximum number of free blocks ever + - Lifetime number of bytes allocated -- Maximum number of blocks searched ever + - Lifetime number of bytes freed -- Lifetime number of bytes allocated + - Total number of searches -- Lifetime number of bytes freed + - Total number of successful allocations -- Total number of searches + - Total number of failed allocations -- Total number of successful allocations + - Total number of successful frees -- Total number of failed allocations + - Total number of successful resizes -- Total number of successful frees + When the subcommand ``walk`` is specified, then a heap walk will be + performed and information about each block is printed out. -- Total number of successful resizes +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -When the subcommand ``walk`` is specified, then a heap walk will be performed -and information about each block is printed out. +NOTES: + NONE -**EXIT STATUS:** +EXAMPLES: + The following is an example of how to use the ``malloc`` command. -This command returns 0 on success and non-zero if an error is encountered. + .. code-block:: shell -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use the ``malloc`` command. - -.. code-block:: shell - - SHLL [/] $ malloc - C Program Heap and RTEMS Workspace are the same. - Number of free blocks: 2 - Largest free block: 266207504 - Total bytes free: 266208392 - Number of used blocks: 167 - Largest used block: 16392 - Total bytes used: 83536 - Size of the allocatable area in bytes: 266291928 - Minimum free size ever in bytes: 266207360 - Maximum number of free blocks ever: 6 - Maximum number of blocks searched ever: 5 - Lifetime number of bytes allocated: 91760 - Lifetime number of bytes freed: 8224 - Total number of searches: 234 - Total number of successful allocations: 186 - Total number of failed allocations: 0 - Total number of successful frees: 19 - Total number of successful resizes: 0 - SHLL [/] $ malloc walk - malloc walk - PASS[0]: page size 8, min block size 48 - area begin 0x00210210, area end 0x0FFFC000 - first block 0x00210214, last block 0x0FFFBFDC - first free 0x00228084, last free 0x00228354 - PASS[0]: block 0x00210214: size 88 - ... - PASS[0]: block 0x00220154: size 144 - PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free) - PASS[0]: block 0x0022028C: size 168, prev_size 168 - ... - PASS[0]: block 0x00226E7C: size 4136 - PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4 - PASS[0]: block 0x0022803C: size 72, prev_size 408 - PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4 - PASS[0]: block 0x0022830C: size 72, prev_size 648 - PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail) - PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192 - -**CONFIGURATION:** + SHLL [/] $ malloc + C Program Heap and RTEMS Workspace are the same. + Number of free blocks: 2 + Largest free block: 266207504 + Total bytes free: 266208392 + Number of used blocks: 167 + Largest used block: 16392 + Total bytes used: 83536 + Size of the allocatable area in bytes: 266291928 + Minimum free size ever in bytes: 266207360 + Maximum number of free blocks ever: 6 + Maximum number of blocks searched ever: 5 + Lifetime number of bytes allocated: 91760 + Lifetime number of bytes freed: 8224 + Total number of searches: 234 + Total number of successful allocations: 186 + Total number of failed allocations: 0 + Total number of successful frees: 19 + Total number of successful resizes: 0 + SHLL [/] $ malloc walk + malloc walk + PASS[0]: page size 8, min block size 48 + area begin 0x00210210, area end 0x0FFFC000 + first block 0x00210214, last block 0x0FFFBFDC + first free 0x00228084, last free 0x00228354 + PASS[0]: block 0x00210214: size 88 + ... + PASS[0]: block 0x00220154: size 144 + PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free) + PASS[0]: block 0x0022028C: size 168, prev_size 168 + ... + PASS[0]: block 0x00226E7C: size 4136 + PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4 + PASS[0]: block 0x0022803C: size 72, prev_size 408 + PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4 + PASS[0]: block 0x0022830C: size 72, prev_size 648 + PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail) + PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192 .. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC .. index:: CONFIGURE_SHELL_COMMAND_MALLOC -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all shell commands have been + configured. .. 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 + .. code-block:: c - int rtems_shell_rtems_main_malloc( - int argc, - char **argv - ); + int rtems_shell_rtems_main_malloc( + int argc, + char **argv + ); -The configuration structure for the ``malloc`` has the following prototype: + The configuration structure for the ``malloc`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; + extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; diff --git a/shell/network_commands.rst b/shell/network_commands.rst index 985706a..5deaa73 100644 --- a/shell/network_commands.rst +++ b/shell/network_commands.rst @@ -27,190 +27,191 @@ 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:** - -.. code-block:: shell - - netstats [-Aimfpcut] - -**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: - -*-A* - print All statistics - -*-i* - print Inet Routes - -*-m* - print MBUF Statistics - -*-f* - print IF Statistics - -*-p* - print IP Statistics - -*-c* - print ICMP Statistics +SYNOPSYS: + .. code-block:: shell -*-u* - print UDP Statistics + netstats [-Aimfpcut] -*-t* - print TCP Statistics +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: -**EXIT STATUS:** + *-A* + print All statistics -This command returns 0 on success and non-zero if an error is encountered. + *-i* + print Inet Routes -**NOTES:** + *-m* + print MBUF Statistics -NONE + *-f* + print IF Statistics -**EXAMPLES:** + *-p* + print IP Statistics -The following is an example of using the ``netstats`` command to print the IP -routing table: + *-c* + print ICMP Statistics -.. code-block:: shell + *-u* + print UDP Statistics - [/] $ netstats -i - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1219 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 + *-t* + print TCP Statistics -The following is an example of using the ``netstats`` command to print the MBUF -statistics: +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -.. code-block:: shell +NOTES: + NONE + +EXAMPLES: + The following is an example of using the ``netstats`` command to print the + IP routing table: - [/] $ netstats -m - ************ MBUF STATISTICS ************ - mbufs:2048 clusters: 128 free: 63 - drops: 0 waits: 0 drains: 0 - free:1967 data:79 header:2 socket:0 - pcb:0 rtable:0 htable:0 atable:0 - soname:0 soopts:0 ftable:0 rights:0 - ifaddr:0 control:0 oobdata:0 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the -print the interface statistics: + [/] $ netstats -i + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1219 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 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + MBUF statistics: - [/] $ netstats -f - ************ INTERFACE STATISTICS ************ - ***** eth1 ***** - Ethernet Address: 00:04:9F:00:5B:21 - Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0 - Flags: Up Broadcast Running Active Multicast - Send queue limit:50 length:1 Dropped:0 - Rx Interrupts:889 Not First:0 Not Last:0 - Giant:0 Non-octet:0 - Bad CRC:0 Overrun:0 Collision:0 - Tx Interrupts:867 Deferred:0 Late Collision:0 - Retransmit Limit:0 Underrun:0 Misaligned:0 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the -print IP statistics: + [/] $ netstats -m + ************ MBUF STATISTICS ************ + mbufs:2048 clusters: 128 free: 63 + drops: 0 waits: 0 drains: 0 + free:1967 data:79 header:2 socket:0 + pcb:0 rtable:0 htable:0 atable:0 + soname:0 soopts:0 ftable:0 rights:0 + ifaddr:0 control:0 oobdata:0 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + print the interface statistics: - [/] $ netstats -p - ************ IP Statistics ************ - total packets received 894 - packets rcvd for unreachable dest 13 - datagrams delivered to upper level 881 - total ip packets generated here 871 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the ICMP -statistics: + [/] $ netstats -f + ************ INTERFACE STATISTICS ************ + ***** eth1 ***** + Ethernet Address: 00:04:9F:00:5B:21 + Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0 + Flags: Up Broadcast Running Active Multicast + Send queue limit:50 length:1 Dropped:0 + Rx Interrupts:889 Not First:0 Not Last:0 + Giant:0 Non-octet:0 + Bad CRC:0 Overrun:0 Collision:0 + Tx Interrupts:867 Deferred:0 Late Collision:0 + Retransmit Limit:0 Underrun:0 Misaligned:0 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + print IP statistics: - [/] $ netstats -c - ************ ICMP Statistics ************ - Type 0 sent 843 - number of responses 843 - Type 8 received 843 + .. code-block:: shell -The following is an example of using the ``netstats`` command to print the UDP -statistics: + [/] $ netstats -p + ************ IP Statistics ************ + total packets received 894 + packets rcvd for unreachable dest 13 + datagrams delivered to upper level 881 + total ip packets generated here 871 -.. code-block:: shell + The following is an example of using the ``netstats`` command to print the + ICMP statistics: + + .. code-block:: shell - [/] $ netstats -u - ************ UDP Statistics ************ - -The following is an example of using the ``netstats`` command to print the TCP -statistics: - -.. code-block:: shell - - [/] $ netstats -t - ************ TCP Statistics ************ - connections accepted 1 - connections established 1 - segs where we tried to get rtt 34 - times we succeeded 35 - delayed acks sent 2 - total packets sent 37 - data packets sent 35 - data bytes sent 2618 - ack-only packets sent 2 - total packets received 47 - packets received in sequence 12 - bytes received in sequence 307 - rcvd ack packets 35 - bytes acked by rcvd acks 2590 - times hdr predict ok for acks 27 - times hdr predict ok for data pkts 10 - -**CONFIGURATION:** + [/] $ netstats -c + ************ ICMP Statistics ************ + Type 0 sent 843 + number of responses 843 + Type 8 received 843 + + 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: + + .. code-block:: shell + + [/] $ netstats -t + ************ TCP Statistics ************ + connections accepted 1 + connections established 1 + segs where we tried to get rtt 34 + times we succeeded 35 + delayed acks sent 2 + total packets sent 37 + data packets sent 35 + data bytes sent 2618 + ack-only packets sent 2 + total packets received 47 + packets received in sequence 12 + bytes received in sequence 307 + rcvd ack packets 35 + bytes acked by rcvd acks 2590 + times hdr predict ok for acks 27 + times hdr predict ok for data pkts 10 .. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS .. index:: CONFIGURE_SHELL_COMMAND_NETSTATS -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. +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. -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:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all shell commands have been + configured. .. 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 + + int rtems_shell_rtems_main_netstats( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``netstats`` has the following prototype: - int rtems_shell_rtems_main_netstats( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``netstats`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; + \clearpage .. _ifconfig: @@ -218,79 +219,77 @@ ifconfig - configure a network interface ---------------------------------------- .. index:: ifconfig -**SYNOPSYS:** - -.. code-block:: shell - - ifconfig - ifconfig 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:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: shell -**NOTES:** + ifconfig + ifconfig interface + ifconfig interface \[up|down] + ifconfig interface \[netmask|pointtopoint|broadcast] IP -Just like its counterpart on GNU/Linux and BSD systems, this command is -complicated. More example usages would be a welcome submission. +DESCRIPTION: + This command may be used to display information about the network + interfaces in the system or configure them. -**EXAMPLES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The following is an example of how to use ``ifconfig``: +NOTES: + Just like its counterpart on GNU/Linux and BSD systems, this command is + complicated. More example usages would be a welcome submission. -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``ifconfig``: - ************ INTERFACE STATISTICS ************ - ***** eth1 ***** - Ethernet Address: 00:04:9F:00:5B:21 - Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0 - Flags: Up Broadcast Running Active Multicast - Send queue limit:50 length:1 Dropped:0 - Rx Interrupts:5391 Not First:0 Not Last:0 - Giant:0 Non-octet:0 - Bad CRC:0 Overrun:0 Collision:0 - Tx Interrupts:5256 Deferred:0 Late Collision:0 - Retransmit Limit:0 Underrun:0 Misaligned:0 + .. code-block:: shell -**CONFIGURATION:** + ************ INTERFACE STATISTICS ************ + ***** eth1 ***** + Ethernet Address: 00:04:9F:00:5B:21 + Address:192.168.1.244 Broadcast Address:192.168.1.255 Net mask:255.255.255.0 + Flags: Up Broadcast Running Active Multicast + Send queue limit:50 length:1 Dropped:0 + Rx Interrupts:5391 Not First:0 Not Last:0 + Giant:0 Non-octet:0 + Bad CRC:0 Overrun:0 Collision:0 + Tx Interrupts:5256 Deferred:0 Late Collision:0 + Retransmit Limit:0 Underrun:0 Misaligned:0 .. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG .. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG -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. +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. -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:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ifconfig -The ``ifconfig`` is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``ifconfig`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_ifconfig( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``ifconfig`` has the following + prototype: - int rtems_shell_rtems_main_ifconfig( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``ifconfig`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; + \clearpage .. _route: @@ -298,101 +297,98 @@ route - show or manipulate the ip routing table ----------------------------------------------- .. index:: route -**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. - -Command templates include the following: - -.. code-block:: shell - - route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK] - route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK] - -When not provided the netmask defaults to ``255.255.255.0`` - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -Just like its counterpart on GNU/Linux and BSD systems, this command is -complicated. More example usages would be a welcome submission. - -**EXAMPLES:** - -The following is an example of how to use ``route`` to display, add, and delete -a new route: - -.. code-block:: shell - - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1444 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 10844 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 37 1399 eth1 - [/] $ route add -net 192.168.3.0 gw 192.168.1.14 - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 2 0 1498 eth1 - 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 14937 1202 eth1 - 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 96 1399 eth1 - 192.168.3.0 192.168.1.14 UGS 0 0 0 eth1 - [/] $ route del -net 192.168.3.0 gw 192.168.1.14 - [/] $ route - Destination Gateway/Mask/Hw Flags Refs Use Expire Interface - default 192.168.1.14 UGS 0 0 0 eth1 - 192.168.1.0 255.255.255.0 U 0 0 1 eth1 - 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1498 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 - -**CONFIGURATION:** +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. + + Command templates include the following: + + .. code-block:: shell + + route [add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS [netmask MASK] + route [add|del] -host IP_ADDRESS gw GATEWAY_ADDRES [netmask MASK] + + When not provided the netmask defaults to ``255.255.255.0`` + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + Just like its counterpart on GNU/Linux and BSD systems, this command is + complicated. More example usages would be a welcome submission. + +EXAMPLES: + The following is an example of how to use ``route`` to display, add, and + delete a new route: + + .. code-block:: shell + + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1444 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 10844 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 37 1399 eth1 + [/] $ route add -net 192.168.3.0 gw 192.168.1.14 + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 2 0 1498 eth1 + 192.168.1.51 00:1D:7E:0C:D0:7C UHL 0 14937 1202 eth1 + 192.168.1.151 00:1C:23:B2:0F:BB UHL 2 96 1399 eth1 + 192.168.3.0 192.168.1.14 UGS 0 0 0 eth1 + [/] $ route del -net 192.168.3.0 gw 192.168.1.14 + [/] $ route + Destination Gateway/Mask/Hw Flags Refs Use Expire Interface + default 192.168.1.14 UGS 0 0 0 eth1 + 192.168.1.0 255.255.255.0 U 0 0 1 eth1 + 192.168.1.14 00:A0:C8:1C:EE:28 UHL 1 0 1498 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 .. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE .. index:: CONFIGURE_SHELL_COMMAND_ROUTE -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all shell commands have been + configured. .. 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 + .. code-block:: c - int rtems_shell_rtems_main_route( - int argc, - char **argv - ); + int rtems_shell_rtems_main_route( + int argc, + char **argv + ); -The configuration structure for the ``route`` has the following prototype: + The configuration structure for the ``route`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + +.. raw:: latex + + \clearpage .. _ping: @@ -400,255 +396,253 @@ ping - ping a host or IP address -------------------------------- .. index:: ping -**SYNOPSYS:** - -.. code-block:: shell - - ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize] - [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl] - [-p pattern] [-S src_addr] [-s packetsize] [-t timeout] - [-W waittime] [-z tos] host - ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload] - [-M mask | time] [-m ttl] [-p pattern] [-S src_addr] - [-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: - -*-A* - Audible. Output a bell (ASCII 0x07) character when no packet is received - before the next packet is transmitted. To cater for round-trip times that - are longer than the interval between transmissions, further missing packets - cause a bell only if the maximum number of unreceived packets has - increased. - -*-a* - Audible. Include a bell (ASCII 0x07) character in the output when any - packet is received. This option is ignored if other format options are - 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. - -*-D* - Set the Don't Fragment bit. - -*-d* - 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. - -*-G sweepmaxsize* - 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. - -*-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. - -*-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. - -*-L* - 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. - -*-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. - -*-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. - -*-n* - 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. - -*-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. - -*-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. - -*-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). - -*-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. - -*-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. - -*-T ttl* - 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. - -*-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. - -*-z tos* - Use the specified type of service. - -**EXIT STATUS:** - -The ping utility exits with one of the following values: - -0 At least one response was heard from the specified host. - -2 The transmission was successful but no responses were - received. - -any other value an error occurred. These values are defined in . - -**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. - -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 - - [/] # ping 10.10.10.1 - PING 10.10.10.1 (10.10.10.1): 56 data bytes - 64 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms - 64 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms - 64 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms - 64 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms - 64 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms - --- 10.10.10.1 ping statistics --- - 5 packets transmitted, 5 packets received, 0.0% packet loss - round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms - [/] # ping -f -c 10000 10.10.10.1 - PING 10.10.10.1 (10.10.10.1): 56 data bytes - . - --- 10.10.10.1 ping statistics --- - 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:** +SYNOPSYS: + .. code-block:: shell + + ping [-AaDdfnoQqRrv] [-c count] [-G sweepmaxsize] [-g sweepminsize] + [-h sweepincrsize] [-i wait] [-l preload] [-M mask | time] [-m ttl] + [-p pattern] [-S src_addr] [-s packetsize] [-t timeout] + [-W waittime] [-z tos] host + ping [-AaDdfLnoQqRrv] [-c count] [-I iface] [-i wait] [-l preload] + [-M mask | time] [-m ttl] [-p pattern] [-S src_addr] + [-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: + + *-A* + Audible. Output a bell (ASCII 0x07) character when no packet is + received before the next packet is transmitted. To cater for + round-trip times that are longer than the interval between + transmissions, further missing packets cause a bell only if the maximum + number of unreceived packets has increased. + + *-a* + Audible. Include a bell (ASCII 0x07) character in the output when any + packet is received. This option is ignored if other format options are + 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. + + *-D* + Set the Don't Fragment bit. + + *-d* + 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. + + *-G sweepmaxsize* + 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. + + *-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. + + *-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. + + *-L* + 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. + + *-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. + + *-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. + + *-n* + 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. + + *-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. + + *-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. + + *-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). + + *-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. + + *-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. + + *-T ttl* + 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. + + *-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. + + *-z tos* + Use the specified type of service. + +EXIT STATUS: + The ping utility exits with one of the following values: + + 0 At least one response was heard from the specified host. + + 2 The transmission was successful but no responses were + received. + + any other value an error occurred. These values are defined in + . + +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. + + 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 + + [/] # ping 10.10.10.1 + PING 10.10.10.1 (10.10.10.1): 56 data bytes + 64 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms + 64 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms + 64 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms + 64 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms + 64 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms + --- 10.10.10.1 ping statistics --- + 5 packets transmitted, 5 packets received, 0.0% packet loss + round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms + [/] # ping -f -c 10000 10.10.10.1 + PING 10.10.10.1 (10.10.10.1): 56 data bytes + . + --- 10.10.10.1 ping statistics --- + 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 .. index:: CONFIGURE_SHELL_NO_COMMAND_PING .. index:: CONFIGURE_SHELL_COMMAND_PING -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. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been -configured. +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. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PING`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_ping -The ``ping`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``ping`` is implemented by a C language function which has the following + prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_ping( - int argc, - char **argv - ); + int rtems_shell_rtems_main_ping( + int argc, + char **argv + ); -The configuration structure for the ``ping`` has the following prototype: + The configuration structure for the ``ping`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_PING_Command; + extern rtems_shell_cmd_t rtems_shell_PING_Command; diff --git a/shell/rtems_specific_commands.rst b/shell/rtems_specific_commands.rst index 1cfd7a8..324f8d3 100644 --- a/shell/rtems_specific_commands.rst +++ b/shell/rtems_specific_commands.rst @@ -51,10 +51,13 @@ The RTEMS shell has the following RTEMS specific commands: Commands ======== -This section details the RTEMS Specific 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. +This section details the RTEMS Specific 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 .. _shutdown: @@ -62,53 +65,53 @@ shutdown - Shutdown the system ------------------------------ .. index:: shutdown -**SYNOPSYS:** - -.. code-block:: shell - - shutdown - -**DESCRIPTION:** - -This command is used to shutdown the RTEMS application. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + shutdown -This command does not return. +DESCRIPTION: + This command is used to shutdown the RTEMS application. -**NOTES:** +EXIT STATUS: + This command does not return. -**EXAMPLES:** +NOTES: + NONE -The following is an example of how to use ``shutdown``: +EXAMPLES: + The following is an example of how to use ``shutdown``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ shutdown - System shutting down at user request + SHLL [/] $ shutdown + System shutting down at user request -The user will not see another prompt and the system will shutdown. - -**CONFIGURATION:** + The user will not see another prompt and the system will shutdown. .. index:: CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN .. index:: CONFIGURE_SHELL_COMMAND_SHUTDOWN -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_SHUTDOWN`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_SHUTDOWN`` to have + this command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN`` when all shell commands have been -configured. +PROGRAMMING INFORMATION: + The configuration structure for the ``shutdown`` has the following + prototype: -**PROGRAMMING INFORMATION:** + .. code-block:: c -The configuration structure for the ``shutdown`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command; + \clearpage .. _cpuuse: @@ -116,92 +119,89 @@ cpuuse - print or reset per thread cpu usage -------------------------------------------- .. index:: cpuuse -**SYNOPSYS:** - -.. code-block:: shell - - cpuuse [-r] - -**DESCRIPTION:** - -This command may be used to print a report on the per thread cpu usage or to -reset the per thread CPU usage statistics. When invoked with the ``-r`` option, -the CPU usage statistics are reset. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -The granularity of the timing information reported is dependent upon the BSP -and the manner in which RTEMS was built. In the default RTEMS configuration, -if the BSP supports nanosecond granularity timestamps, then the information -reported will be highly accurate. Otherwise, the accuracy of the information -reported is limited by the clock tick quantum. - -**EXAMPLES:** - -The following is an example of how to use ``cpuuse``: - -.. code-block:: shell - - SHLL [/] $ cpuuse - CPU Usage by thread - ID NAME SECONDS PERCENT - 0x09010001 IDLE 49.745393 98.953 - 0x0a010001 UI1 0.000000 0.000 - 0x0a010002 SHLL 0.525928 1.046 - Time since last CPU Usage reset 50.271321 seconds - SHLL [/] $ cpuuse -r - Resetting CPU Usage information - SHLL [/] $ cpuuse - CPU Usage by thread - ID NAME SECONDS PERCENT - 0x09010001 IDLE 0.000000 0.000 - 0x0a010001 UI1 0.000000 0.000 - 0x0a010002 SHLL 0.003092 100.000 - Time since last CPU Usage reset 0.003092 seconds - -In the above example, the system had set idle for nearly a minute when the -first report was generated. The``cpuuse -r`` and ``cpuuse`` commands were -pasted from another window so were executed with no gap between. In the second -report, only the ``shell`` thread has run since the CPU Usage was reset. It -has consumed approximately 3.092 milliseconds of CPU time processing the two -commands and generating the output. - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + cpuuse [-r] + +DESCRIPTION: + This command may be used to print a report on the per thread cpu usage or + to reset the per thread CPU usage statistics. When invoked with the ``-r`` + option, the CPU usage statistics are reset. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + The granularity of the timing information reported is dependent upon the + BSP and the manner in which RTEMS was built. In the default RTEMS + configuration, if the BSP supports nanosecond granularity timestamps, then + the information reported will be highly accurate. Otherwise, the accuracy + of the information reported is limited by the clock tick quantum. + +EXAMPLES: + The following is an example of how to use ``cpuuse``: + + .. code-block:: shell + + SHLL [/] $ cpuuse + CPU Usage by thread + ID NAME SECONDS PERCENT + 0x09010001 IDLE 49.745393 98.953 + 0x0a010001 UI1 0.000000 0.000 + 0x0a010002 SHLL 0.525928 1.046 + Time since last CPU Usage reset 50.271321 seconds + SHLL [/] $ cpuuse -r + Resetting CPU Usage information + SHLL [/] $ cpuuse + CPU Usage by thread + ID NAME SECONDS PERCENT + 0x09010001 IDLE 0.000000 0.000 + 0x0a010001 UI1 0.000000 0.000 + 0x0a010002 SHLL 0.003092 100.000 + Time since last CPU Usage reset 0.003092 seconds + + In the above example, the system had set idle for nearly a minute when the + first report was generated. The``cpuuse -r`` and ``cpuuse`` commands were + pasted from another window so were executed with no gap between. In the + second report, only the ``shell`` thread has run since the CPU Usage was + reset. It has consumed approximately 3.092 milliseconds of CPU time + processing the two commands and generating the output. .. index:: CONFIGURE_SHELL_NO_COMMAND_CPUUSE .. index:: CONFIGURE_SHELL_COMMAND_CPUUSE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CPUUSE`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CPUUSE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CPUUSE`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CPUUSE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_cpuuse -The ``cpuuse`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``cpuuse`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_cpuuse( + int argc, + char **argv + ); - int rtems_shell_rtems_main_cpuuse( - int argc, - char **argv - ); + The configuration structure for the ``cpuuse`` has the following prototype: -The configuration structure for the ``cpuuse`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command; - extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command; +.. raw:: latex + + \clearpage .. _stackuse: @@ -209,74 +209,71 @@ stackuse - print per thread stack usage --------------------------------------- .. index:: stackuse -**SYNOPSYS:** - -.. code-block:: shell - - stackuse +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + stackuse -This command prints a Stack Usage Report for all of the tasks and threads in -the system. On systems which support it, the usage of the interrupt stack is -also included in the report. +DESCRIPTION: + This command prints a Stack Usage Report for all of the tasks and threads + in the system. On systems which support it, the usage of the interrupt + stack is also included in the report. -**EXIT STATUS:** +EXIT STATUS: + This command always succeeds and returns 0. -This command always succeeds and returns 0. +NOTES: + The ``CONFIGURE_STACK_CHECKER_ENABLED`` ``confdefs.h`` constant must be + defined when the application is configured for this command to have any + information to report. -**NOTES:** +EXAMPLES: + The following is an example of how to use ``stackuse``: -The ``CONFIGURE_STACK_CHECKER_ENABLED`` ``confdefs.h`` constant must be defined -when the application is configured for this command to have any information to -report. + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``stackuse``: - -.. code-block:: shell - - SHLL [/] $ stackuse - Stack usage by thread - ID NAME LOW HIGH CURRENT AVAILABLE USED - 0x09010001 IDLE 0x023d89a0 - 0x023d99af 0x023d9760 4096 608 - 0x0a010001 UI1 0x023d9f30 - 0x023daf3f 0x023dad18 4096 1804 - 0x0a010002 SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0 16384 5116 - 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 - -**CONFIGURATION:** + SHLL [/] $ stackuse + Stack usage by thread + ID NAME LOW HIGH CURRENT AVAILABLE USED + 0x09010001 IDLE 0x023d89a0 - 0x023d99af 0x023d9760 4096 608 + 0x0a010001 UI1 0x023d9f30 - 0x023daf3f 0x023dad18 4096 1804 + 0x0a010002 SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0 16384 5116 + 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 .. index:: CONFIGURE_SHELL_NO_COMMAND_STACKUSE .. index:: CONFIGURE_SHELL_COMMAND_STACKUSE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_STACKUSE`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_STACKUSE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_STACKUSE`` to have + this command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_STACKUSE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_stackuse -The ``stackuse`` is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``stackuse`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_stackuse( - int argc, - char **argv - ); + int rtems_shell_rtems_main_stackuse( + int argc, + char **argv + ); -The configuration structure for the ``stackuse`` has the following prototype: + The configuration structure for the ``stackuse`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command; + extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command; + +.. raw:: latex + + \clearpage .. _perioduse: @@ -284,94 +281,91 @@ perioduse - print or reset per period usage ------------------------------------------- .. index:: perioduse -**SYNOPSYS:** - -.. code-block:: shell - - perioduse [-r] - -**DESCRIPTION:** - -This command may be used to print a statistics report on the rate monotonic -periods in the application or to reset the rate monotonic period usage -statistics. When invoked with the ``-r`` option, the usage statistics are -reset. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -The granularity of the timing information reported is dependent upon the BSP -and the manner in which RTEMS was built. In the default RTEMS configuration, -if the BSP supports nanosecond granularity timestamps, then the information -reported will be highly accurate. Otherwise, the accuracy of the information -reported is limited by the clock tick quantum. - -**EXAMPLES:** - -The following is an example of how to use ``perioduse``: - -.. code-block:: shell - - SHLL [/] $ perioduse - Period information by period - --- CPU times are in seconds --- - --- Wall times are in seconds --- - ID OWNER COUNT MISSED CPU TIME WALL TIME - MIN/MAX/AVG MIN/MAX/AVG - 0x42010001 TA1 502 0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848 - 0x42010002 TA2 502 0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848 - 0x42010003 TA3 501 0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814 - 0x42010004 TA4 501 0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814 - 0x42010005 TA5 10 0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058 - MIN/MAX/AVG MIN/MAX/AVG - SHLL [/] $ perioduse -r - Resetting Period Usage information - SHLL [/] $ perioduse - --- CPU times are in seconds --- - --- Wall times are in seconds --- - ID OWNER COUNT MISSED CPU TIME WALL TIME - MIN/MAX/AVG MIN/MAX/AVG - 0x42010001 TA1 0 0 - 0x42010002 TA2 0 0 - 0x42010003 TA3 0 0 - 0x42010004 TA4 0 0 - 0x42010005 TA5 0 0 - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + perioduse [-r] + +DESCRIPTION: + This command may be used to print a statistics report on the rate monotonic + periods in the application or to reset the rate monotonic period usage + statistics. When invoked with the ``-r`` option, the usage statistics are + reset. + +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. + +NOTES: + The granularity of the timing information reported is dependent upon the + BSP and the manner in which RTEMS was built. In the default RTEMS + configuration, if the BSP supports nanosecond granularity timestamps, then + the information reported will be highly accurate. Otherwise, the accuracy + of the information reported is limited by the clock tick quantum. + +EXAMPLES: + The following is an example of how to use ``perioduse``: + + .. code-block:: shell + + SHLL [/] $ perioduse + Period information by period + --- CPU times are in seconds --- + --- Wall times are in seconds --- + ID OWNER COUNT MISSED CPU TIME WALL TIME + MIN/MAX/AVG MIN/MAX/AVG + 0x42010001 TA1 502 0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848 + 0x42010002 TA2 502 0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848 + 0x42010003 TA3 501 0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814 + 0x42010004 TA4 501 0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814 + 0x42010005 TA5 10 0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058 + MIN/MAX/AVG MIN/MAX/AVG + SHLL [/] $ perioduse -r + Resetting Period Usage information + SHLL [/] $ perioduse + --- CPU times are in seconds --- + --- Wall times are in seconds --- + ID OWNER COUNT MISSED CPU TIME WALL TIME + MIN/MAX/AVG MIN/MAX/AVG + 0x42010001 TA1 0 0 + 0x42010002 TA2 0 0 + 0x42010003 TA3 0 0 + 0x42010004 TA4 0 0 + 0x42010005 TA5 0 0 .. index:: CONFIGURE_SHELL_NO_COMMAND_PERIODUSE .. index:: CONFIGURE_SHELL_COMMAND_PERIODUSE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_PERIODUSE`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PERIODUSE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_PERIODUSE`` to have + this command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PERIODUSE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_perioduse -The ``perioduse`` is implemented by a C language function -which has the following prototype: +PROGRAMMING INFORMATION: + The ``perioduse`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_perioduse( - int argc, - char **argv - ); + int rtems_shell_rtems_main_perioduse( + int argc, + char **argv + ); -The configuration structure for the ``perioduse`` has the following prototype: + The configuration structure for the ``perioduse`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command; + extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command; + +.. raw:: latex + + \clearpage .. _profreport: @@ -379,103 +373,101 @@ profreport - print a profiling report ------------------------------------- .. index:: profreport -**SYNOPSYS:** - -.. code-block:: shell - - profreport - -**DESCRIPTION:** - -This command may be used to print a profiling report if profiling is built into -the RTEMS kernel. - -**EXIT STATUS:** - -This command returns 0. - -**NOTES:** - -Profiling must be enabled at build configuration time to get profiling -information. - -**EXAMPLES:** - -The following is an example of how to use ``profreport``: - -.. code-block:: shell - - SHLL [/] $ profreport - - - 10447 - 2 - 195926627 - 77908688 - 0 - 688 - 127 - 282651157 - 2215855 - - - 9053 - 41 - 3053830335 - 73334202 - 0 - 57 - 35 - 76980203 - 2141179 - - - 608 - 1387 - 112 - 338 - 119031 - 357222 - 1055 - 1055 - 0 - 0 - 0 - - - 4186 - 7575 - 160 - 183 - 1772793111 - 2029733879 - 11039140 - 11037655 - 1485 - 0 - 0 - - - -**CONFIGURATION:** +SYNOPSYS: + .. code-block:: shell + + profreport + +DESCRIPTION: + This command may be used to print a profiling report if profiling is built + into the RTEMS kernel. + +EXIT STATUS: + This command returns 0. + +NOTES: + Profiling must be enabled at build configuration time to get profiling + information. + +EXAMPLES: + The following is an example of how to use ``profreport``: + + .. code-block:: shell + + SHLL [/] $ profreport + + + 10447 + 2 + 195926627 + 77908688 + 0 + 688 + 127 + 282651157 + 2215855 + + + 9053 + 41 + 3053830335 + 73334202 + 0 + 57 + 35 + 76980203 + 2141179 + + + 608 + 1387 + 112 + 338 + 119031 + 357222 + 1055 + 1055 + 0 + 0 + 0 + + + 4186 + 7575 + 160 + 183 + 1772793111 + 2029733879 + 11039140 + 11037655 + 1485 + 0 + 0 + + .. index:: CONFIGURE_SHELL_NO_COMMAND_PROFREPORT .. index:: CONFIGURE_SHELL_COMMAND_PROFREPORT -When building a custom command set, define -``CONFIGURE_SHELL_COMMAND_PROFREPORT`` to have this command included. +CONFIGURATION: + When building a custom command set, define + ``CONFIGURE_SHELL_COMMAND_PROFREPORT`` to have this command included. + + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PROFREPORT`` when all shell commands have been + configured. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PROFREPORT`` when all shell commands have been -configured. +PROGRAMMING INFORMATION: + The configuration structure for the ``profreport`` has the following + prototype: -**PROGRAMMING INFORMATION:** + .. code-block:: c -The configuration structure for the ``profreport`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command; + \clearpage .. _wkspace: @@ -483,83 +475,80 @@ wkspace - display information on executive workspace ---------------------------------------------------- .. index:: wkspace -**SYNOPSYS:** - -.. code-block:: shell - - wkspace +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + wkspace -This command prints information on the current state of the RTEMS Executive -Workspace reported. This includes the following information: +DESCRIPTION: + This command prints information on the current state of the RTEMS Executive + Workspace reported. This includes the following information: -- Number of free blocks + - Number of free blocks -- Largest free block + - Largest free block -- Total bytes free + - Total bytes free -- Number of used blocks + - Number of used blocks -- Largest used block + - Largest used block -- Total bytes used + - Total bytes used -**EXIT STATUS:** +EXIT STATUS: + This command always succeeds and returns 0. -This command always succeeds and returns 0. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of how to use ``wkspace``: -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use ``wkspace``: - -.. code-block:: shell - - SHLL [/] $ wkspace - Number of free blocks: 1 - Largest free block: 132336 - Total bytes free: 132336 - Number of used blocks: 36 - Largest used block: 16408 - Total bytes used: 55344 - -**CONFIGURATION:** + SHLL [/] $ wkspace + Number of free blocks: 1 + Largest free block: 132336 + Total bytes free: 132336 + Number of used blocks: 36 + Largest used block: 16408 + Total bytes used: 55344 .. index:: CONFIGURE_SHELL_NO_COMMAND_WKSPACE .. index:: CONFIGURE_SHELL_COMMAND_WKSPACE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_WKSPACE`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_WKSPACE`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_WKSPACE`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_WKSPACE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_wkspace -The ``wkspace`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``wkspace`` is implemented by a C language function which has the + following prototype: -.. code-block:: c + .. code-block:: c - int rtems_shell_rtems_main_wkspace( - int argc, - char **argv - ); + int rtems_shell_rtems_main_wkspace( + int argc, + char **argv + ); -The configuration structure for the ``wkspace`` has the following prototype: + The configuration structure for the ``wkspace`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command; + extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command; + +.. raw:: latex + + \clearpage .. _config: @@ -567,72 +556,69 @@ config - show the system configuration. --------------------------------------- .. index:: config -**SYNOPSYS:** - -.. code-block:: shell - - config - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -This command display information about the RTEMS Configuration. + config -**EXIT STATUS:** +DESCRIPTION: + This command display information about the RTEMS Configuration. -This command always succeeds and returns 0. +EXIT STATUS: + This command always succeeds and returns 0. -**NOTES:** +NOTES: + At this time, it does not report every configuration parameter. This is an + area in which user submissions or sponsorship of a developer would be + appreciated. -At this time, it does not report every configuration parameter. This is an -area in which user submissions or sponsorship of a developer would be -appreciated. +EXAMPLES: + The following is an example of how to use ``config``: -**EXAMPLES:** + .. code-block:: shell -The following is an example of how to use ``config``: + SHLL [/] $ config + INITIAL (startup) Configuration Info -.. code-block:: shell - - SHLL [/] $ config - INITIAL (startup) Configuration Info - - WORKSPACE start: 0x23d22e0; size: 0x2dd20 - TIME usec/tick: 10000; tick/timeslice: 50; tick/sec: 100 - MAXIMUMS tasks: 20; timers: 0; sems: 50; que's: 20; ext's: 1 - partitions: 0; regions: 0; ports: 0; periods: 0 - -**CONFIGURATION:** + WORKSPACE start: 0x23d22e0; size: 0x2dd20 + TIME usec/tick: 10000; tick/timeslice: 50; tick/sec: 100 + MAXIMUMS tasks: 20; timers: 0; sems: 50; que's: 20; ext's: 1 + partitions: 0; regions: 0; ports: 0; periods: 0 .. index:: CONFIGURE_SHELL_NO_COMMAND_CONFIG .. index:: CONFIGURE_SHELL_COMMAND_CONFIG -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_CONFIG`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_CONFIG`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_CONFIG`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_CONFIG`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_config -The ``config`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``config`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_config( + int argc, + char **argv + ); - int rtems_shell_rtems_main_config( - int argc, - char **argv - ); + The configuration structure for the ``config`` has the following prototype: -The configuration structure for the ``config`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_CONFIG_Command; - extern rtems_shell_cmd_t rtems_shell_CONFIG_Command; +.. raw:: latex + + \clearpage .. _itask: @@ -640,70 +626,67 @@ itask - list init tasks for the system -------------------------------------- .. index:: itask -**SYNOPSYS:** - -.. code-block:: shell - - itask - -**DESCRIPTION:** - -This command prints a report on the set of initialization tasks and threads in -the system. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + itask -This command always succeeds and returns 0. +DESCRIPTION: + This command prints a report on the set of initialization tasks and threads + in the system. -**NOTES:** +EXIT STATUS: + This command always succeeds and returns 0. -At this time, it includes only Classic API Initialization Tasks. This is an -area in which user submissions or sponsorship of a developer would be -appreciated. +NOTES: + At this time, it includes only Classic API Initialization Tasks. This is an + area in which user submissions or sponsorship of a developer would be + appreciated. -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``itask``: -The following is an example of how to use ``itask``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ itask - # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE - ------------------------------------------------------------------------------ - 0 UI1 [0x2002258] 0 [0x0] 1 nP DEFAULT 4096 [0x1000] - -**CONFIGURATION:** + SHLL [/] $ itask + # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE + ------------------------------------------------------------------------------ + 0 UI1 [0x2002258] 0 [0x0] 1 nP DEFAULT 4096 [0x1000] .. index:: CONFIGURE_SHELL_NO_COMMAND_ITASK .. index:: CONFIGURE_SHELL_COMMAND_ITASK -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_ITASK`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_ITASK`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_ITASK`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_ITASK`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_itask -The ``itask`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``itask`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_itask( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``itask`` has the following prototype: - int rtems_shell_rtems_main_itask( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``itask`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_ITASK_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_ITASK_Command; + \clearpage .. _extension: @@ -711,71 +694,68 @@ extension - display information about extensions ------------------------------------------------ .. index:: extension -**SYNOPSYS:** - -.. code-block:: shell - - extension [id [id ...]] - -**DESCRIPTION:** - -When invoked with no arguments, this command prints information on the set of -User Extensions currently active in the system. - -If invoked with a set of ids as arguments, then just those objects are included -in the information printed. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + extension [id [id ...]] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of User Extensions currently active in the system. -**NOTES:** + If invoked with a set of ids as arguments, then just those objects are + included in the information printed. -NONE +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + NONE -The following is an example of using the ``extension`` command -on a system with no user extensions. +EXAMPLES: + The following is an example of using the ``extension`` command on a system + with no user extensions. -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ extension - ID NAME - ------------------------------------------------------------------------------ - -**CONFIGURATION:** + SHLL [/] $ extension + ID NAME + ------------------------------------------------------------------------------ .. index:: CONFIGURE_SHELL_NO_COMMAND_EXTENSION .. index:: CONFIGURE_SHELL_COMMAND_EXTENSION -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_EXTENSION`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_EXTENSION`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_EXTENSION`` to have + this command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_EXTENSION`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_extension -The ``extension`` is implemented by a C language function which has the -following prototype: +PROGRAMMING INFORMATION: + The ``extension`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_extension( + int argc, + char **argv + ); - int rtems_shell_rtems_main_extension( - int argc, - char **argv - ); + The configuration structure for the ``extension`` has the following prototype: -The configuration structure for the ``extension`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command; - extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command; +.. raw:: latex + + \clearpage .. _task: @@ -783,73 +763,70 @@ task - display information about tasks -------------------------------------- .. index:: task -**SYNOPSYS:** - -.. code-block:: shell - - task [id [id ...]] +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + task [id [id ...]] -When invoked with no arguments, this command prints information on the set of -Classic API Tasks currently active in the system. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Classic API Tasks currently active in the system. -If invoked with a set of ids as arguments, then just those objects are included -in the information printed. + If invoked with a set of ids as arguments, then just those objects are + included in the information printed. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of how to use the ``task`` on an application + with just two Classic API tasks: -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of how to use the ``task`` on an application with -just two Classic API tasks: - -.. code-block:: shell - - SHLL [/] $ task - ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES - ------------------------------------------------------------------------------ - 0a010001 UI1 1 SUSP P:T:nA NONE - 0a010002 SHLL 100 READY P:T:nA NONE - -**CONFIGURATION:** + SHLL [/] $ task + ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES + ------------------------------------------------------------------------------ + 0a010001 UI1 1 SUSP P:T:nA NONE + 0a010002 SHLL 100 READY P:T:nA NONE .. index:: CONFIGURE_SHELL_NO_COMMAND_TASK .. index:: CONFIGURE_SHELL_COMMAND_TASK -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_TASK`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_TASK`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_TASK`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_TASK`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_task -The ``task`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``task`` is implemented by a C language function which has the + following prototype: -.. code-block:: shell + .. code-block:: shell - int rtems_shell_rtems_main_task( - int argc, - char **argv - ); + int rtems_shell_rtems_main_task( + int argc, + char **argv + ); -The configuration structure for the ``task`` has the following prototype: + The configuration structure for the ``task`` has the following prototype: -.. code-block:: c + .. code-block:: c - extern rtems_shell_cmd_t rtems_shell_TASK_Command; + extern rtems_shell_cmd_t rtems_shell_TASK_Command; + +.. raw:: latex + + \clearpage .. _queue: @@ -857,71 +834,68 @@ queue - display information about message queues ------------------------------------------------ .. index:: queue -**SYNOPSYS:** - -.. code-block:: shell - - queue [id [id ... ]] - -**DESCRIPTION:** +SYNOPSYS: + .. code-block:: shell -When invoked with no arguments, this command prints information on the set of -Classic API Message Queues currently active in the system. + queue [id [id ... ]] -If invoked with a set of ids as arguments, then just those objects are included -in the information printed. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Classic API Message Queues currently active in the system. -**EXIT STATUS:** + If invoked with a set of ids as arguments, then just those objects are + included in the information printed. -This command returns 0 on success and non-zero if an error is encountered. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**NOTES:** +NOTES: + NONE -NONE +EXAMPLES: + The following is an example of using the ``queue`` command on a system with + no Classic API Message Queues. -**EXAMPLES:** + .. code-block:: shell -The following is an example of using the ``queue`` command on a system with no -Classic API Message Queues. - -.. code-block:: shell - - SHLL [/] $ queue - ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE - ------------------------------------------------------------------------------ - -**CONFIGURATION:** + SHLL [/] $ queue + ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE + ------------------------------------------------------------------------------ .. index:: CONFIGURE_SHELL_NO_COMMAND_QUEUE .. index:: CONFIGURE_SHELL_COMMAND_QUEUE -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_QUEUE`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_QUEUE`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_QUEUE`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_QUEUE`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_queue -The ``queue`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``queue`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_queue( + int argc, + char **argv + ); - int rtems_shell_rtems_main_queue( - int argc, - char **argv - ); + The configuration structure for the ``queue`` has the following prototype: -The configuration structure for the ``queue`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_QUEUE_Command; - extern rtems_shell_cmd_t rtems_shell_QUEUE_Command; +.. raw:: latex + + \clearpage .. _sema: @@ -929,78 +903,75 @@ sema - display information about semaphores ------------------------------------------- .. index:: sema -**SYNOPSYS:** - -.. code-block:: shell - - sema [id [id ... ]] - -**DESCRIPTION:** - -When invoked with no arguments, this command prints information on the set of -Classic API Semaphores currently active in the system. - -If invoked with a set of objects ids as arguments, then just those objects are -included in the information printed. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + sema [id [id ... ]] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Classic API Semaphores currently active in the system. -**NOTES:** + If invoked with a set of objects ids as arguments, then just those objects + are included in the information printed. -NONE +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + NONE -The following is an example of how to use ``sema``: +EXAMPLES: + The following is an example of how to use ``sema``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ sema - ID NAME ATTR PRICEIL CURR_CNT HOLDID - ------------------------------------------------------------------------------ - 1a010001 LBIO PR:BI:IN 0 1 00000000 - 1a010002 TRmi PR:BI:IN 0 1 00000000 - 1a010003 LBI00 PR:BI:IN 0 1 00000000 - 1a010004 TRia PR:BI:IN 0 1 00000000 - 1a010005 TRoa PR:BI:IN 0 1 00000000 - 1a010006 TRxa 0 0 09010001 - 1a010007 LBI01 PR:BI:IN 0 1 00000000 - 1a010008 LBI02 PR:BI:IN 0 1 00000000 - -**CONFIGURATION:** + SHLL [/] $ sema + ID NAME ATTR PRICEIL CURR_CNT HOLDID + ------------------------------------------------------------------------------ + 1a010001 LBIO PR:BI:IN 0 1 00000000 + 1a010002 TRmi PR:BI:IN 0 1 00000000 + 1a010003 LBI00 PR:BI:IN 0 1 00000000 + 1a010004 TRia PR:BI:IN 0 1 00000000 + 1a010005 TRoa PR:BI:IN 0 1 00000000 + 1a010006 TRxa 0 0 09010001 + 1a010007 LBI01 PR:BI:IN 0 1 00000000 + 1a010008 LBI02 PR:BI:IN 0 1 00000000 .. index:: CONFIGURE_SHELL_NO_COMMAND_SEMA .. index:: CONFIGURE_SHELL_COMMAND_SEMA -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_SEMA`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_SEMA`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_SEMA`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_SEMA`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_sema -The ``sema`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``sema`` is implemented by a C language function which has the following + prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_sema( + int argc, + char **argv + ); - int rtems_shell_rtems_main_sema( - int argc, - char **argv - ); + The configuration structure for the ``sema`` has the following prototype: -The configuration structure for the ``sema`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_SEMA_Command; - extern rtems_shell_cmd_t rtems_shell_SEMA_Command; +.. raw:: latex + + \clearpage .. _region: @@ -1008,71 +979,68 @@ region - display information about regions ------------------------------------------ .. index:: region -**SYNOPSYS:** - -.. code-block:: shell +SYNOPSYS: + .. code-block:: shell - region [id [id ... ]] + region [id [id ... ]] -**DESCRIPTION:** +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Classic API Regions currently active in the system. -When invoked with no arguments, this command prints information on the set of -Classic API Regions currently active in the system. + If invoked with a set of object ids as arguments, then just those object + are included in the information printed. -If invoked with a set of object ids as arguments, then just those object are -included in the information printed. +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXIT STATUS:** +NOTES: + NONE -This command returns 0 on success and non-zero if an error is encountered. +EXAMPLES: + The following is an example of using the ``region`` command on a system + with no user extensions. -**NOTES:** + .. code-block:: shell -NONE - -**EXAMPLES:** - -The following is an example of using the ``region`` command on a system with no -user extensions. - -.. code-block:: shell - - SHLL [/] $ region - ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS - ------------------------------------------------------------------------------ - -**CONFIGURATION:** + SHLL [/] $ region + ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ .. index:: CONFIGURE_SHELL_NO_COMMAND_REGION .. index:: CONFIGURE_SHELL_COMMAND_REGION -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_REGION`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_REGION`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_REGION`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_REGION`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_region -The ``region`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``region`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_region( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``region`` has the following prototype: - int rtems_shell_rtems_main_region( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``region`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_REGION_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_REGION_Command; + \clearpage .. _part: @@ -1080,71 +1048,68 @@ part - display information about partitions ------------------------------------------- .. index:: part -**SYNOPSYS:** - -.. code-block:: shell - - part [id [id ... ]] +SYNOPSYS: + .. code-block:: shell -**DESCRIPTION:** + part [id [id ... ]] -When invoked with no arguments, this command prints information on the set of -Classic API Partitions currently active in the system. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Classic API Partitions currently active in the system. -If invoked with a set of object ids as arguments, then just those objects are -included in the information printed. + If invoked with a set of object ids as arguments, then just those objects + are included in the information printed. -**EXIT STATUS:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -This command returns 0 on success and non-zero if an error is encountered. +NOTES: + NONE -**NOTES:** +EXAMPLES: + The following is an example of using the ``part`` command on a system with + no user extensions. -NONE + .. code-block:: shell -**EXAMPLES:** - -The following is an example of using the ``part`` command on a system with no -user extensions. - -.. code-block:: shell - - SHLL [/] $ part - ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS - ------------------------------------------------------------------------------ - -**CONFIGURATION:** + SHLL [/] $ part + ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ .. index:: CONFIGURE_SHELL_NO_COMMAND_PART .. index:: CONFIGURE_SHELL_COMMAND_PART -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_PART`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_PART`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_PART`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_PART`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_part -The ``part`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``part`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_part( + int argc, + char **argv + ); - int rtems_shell_rtems_main_part( - int argc, - char **argv - ); + The configuration structure for the ``part`` has the following prototype: -The configuration structure for the ``part`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_PART_Command; - extern rtems_shell_cmd_t rtems_shell_PART_Command; +.. raw:: latex + + \clearpage .. _object: @@ -1152,72 +1117,69 @@ object - display information about RTEMS objects ------------------------------------------------ .. index:: object -**SYNOPSYS:** - -.. code-block:: shell - - object [id [id ...]] - -**DESCRIPTION:** - -When invoked with a set of object ids as arguments, then a report on those -objects is printed. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + object [id [id ...]] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + When invoked with a set of object ids as arguments, then a report on those + objects is printed. -**NOTES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -NONE +NOTES: + NONE -**EXAMPLES:** +EXAMPLES: + The following is an example of how to use ``object``: -The following is an example of how to use ``object``: + .. code-block:: shell -.. code-block:: shell - - SHLL [/] $ object 0a010001 1a010002 - ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES - ------------------------------------------------------------------------------ - 0a010001 UI1 1 SUSP P:T:nA NONE - ID NAME ATTR PRICEIL CURR_CNT HOLDID - ------------------------------------------------------------------------------ - 1a010002 TRmi PR:BI:IN 0 1 00000000 - -**CONFIGURATION:** + SHLL [/] $ object 0a010001 1a010002 + ID NAME PRIO STAT MODES EVENTS WAITID WAITARG NOTES + ------------------------------------------------------------------------------ + 0a010001 UI1 1 SUSP P:T:nA NONE + ID NAME ATTR PRICEIL CURR_CNT HOLDID + ------------------------------------------------------------------------------ + 1a010002 TRmi PR:BI:IN 0 1 00000000 .. index:: CONFIGURE_SHELL_NO_COMMAND_OBJECT .. index:: CONFIGURE_SHELL_COMMAND_OBJECT -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_OBJECT`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_OBJECT`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_OBJECT`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_OBJECT`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_object -The ``object`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``object`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_object( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``object`` has the + following prototype: - int rtems_shell_rtems_main_object( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``object`` has the -following prototype: + extern rtems_shell_cmd_t rtems_shell_OBJECT_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_OBJECT_Command; + \clearpage .. _driver: @@ -1225,77 +1187,74 @@ driver - display the RTEMS device driver table ---------------------------------------------- .. index:: driver -**SYNOPSYS:** - -.. code-block:: shell - - driver [major [major ...]] - -**DESCRIPTION:** - -When invoked with no arguments, this command prints information on the set of -Device Drivers currently active in the system. - -If invoked with a set of major numbers as arguments, then just those Device -Drivers are included in the information printed. +SYNOPSYS: + .. code-block:: shell -**EXIT STATUS:** + driver [major [major ...]] -This command returns 0 on success and non-zero if an error is encountered. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of Device Drivers currently active in the system. -**NOTES:** + If invoked with a set of major numbers as arguments, then just those Device + Drivers are included in the information printed. -NONE +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -**EXAMPLES:** +NOTES: + NONE -The following is an example of how to use ``driver``: +EXAMPLES: + The following is an example of how to use ``driver``: -.. code-block:: shell + .. code-block:: shell - SHLL [/] $ driver - Major Entry points - ------------------------------------------------------------------------------ - 0 init: [0x200256c]; control: [0x20024c8] - open: [0x2002518]; close: [0x2002504] - read: [0x20024f0]; write: [0x20024dc] - 1 init: [0x20023fc]; control: [0x2002448] - open: [0x0]; close: [0x0] - read: [0x0]; write: [0x0] - SHLL [/] $ - -**CONFIGURATION:** + SHLL [/] $ driver + Major Entry points + ------------------------------------------------------------------------------ + 0 init: [0x200256c]; control: [0x20024c8] + open: [0x2002518]; close: [0x2002504] + read: [0x20024f0]; write: [0x20024dc] + 1 init: [0x20023fc]; control: [0x2002448] + open: [0x0]; close: [0x0] + read: [0x0]; write: [0x0] + SHLL [/] $ .. index:: CONFIGURE_SHELL_NO_COMMAND_DRIVER .. index:: CONFIGURE_SHELL_COMMAND_DRIVER -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DRIVER`` to have this -command included. - -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DRIVER`` when all shell commands have been -configured. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DRIVER`` to have this + command included. -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DRIVER`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_driver -The ``driver`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``driver`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c -.. code-block:: c + int rtems_shell_rtems_main_driver( + int argc, + char **argv + ); - int rtems_shell_rtems_main_driver( - int argc, - char **argv - ); + The configuration structure for the ``driver`` has the following prototype: -The configuration structure for the ``driver`` has the following prototype: + .. code-block:: c -.. code-block:: c + extern rtems_shell_cmd_t rtems_shell_DRIVER_Command; - extern rtems_shell_cmd_t rtems_shell_DRIVER_Command; +.. raw:: latex + + \clearpage .. _dname: @@ -1303,64 +1262,61 @@ dname - displays information about named drivers ------------------------------------------------ .. index:: dname -**SYNOPSYS:** - -.. code-block:: shell - - dname - -**DESCRIPTION:** - -WARNING! This command does not appear to work as of 27 February 2008. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: shell -**NOTES:** + dname -NONE +DESCRIPTION: + WARNING! This command does not appear to work as of 27 February 2008. -**EXAMPLES:** +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -The following is an example of how to use ``dname``: +NOTES: + NONE -.. code-block:: shell +EXAMPLES: + The following is an example of how to use ``dname``: - EXAMPLE_TBD + .. code-block:: shell -**CONFIGURATION:** + EXAMPLE_TBD .. index:: CONFIGURE_SHELL_NO_COMMAND_DNAME .. index:: CONFIGURE_SHELL_COMMAND_DNAME -This command is included in the default shell command set. When building a -custom command set, define ``CONFIGURE_SHELL_COMMAND_DNAME`` to have this -command included. +CONFIGURATION: + This command is included in the default shell command set. When building a + custom command set, define ``CONFIGURE_SHELL_COMMAND_DNAME`` to have this + command included. -This command can be excluded from the shell command set by defining -``CONFIGURE_SHELL_NO_COMMAND_DNAME`` when all shell commands have been -configured. - -**PROGRAMMING INFORMATION:** + This command can be excluded from the shell command set by defining + ``CONFIGURE_SHELL_NO_COMMAND_DNAME`` when all shell commands have been + configured. .. index:: rtems_shell_rtems_main_dname -The ``dname`` is implemented by a C language function which has the following -prototype: +PROGRAMMING INFORMATION: + The ``dname`` is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_shell_rtems_main_dname( + int argc, + char **argv + ); -.. code-block:: c + The configuration structure for the ``dname`` has the following prototype: - int rtems_shell_rtems_main_dname( - int argc, - char **argv - ); + .. code-block:: c -The configuration structure for the ``dname`` has the following prototype: + extern rtems_shell_cmd_t rtems_shell_DNAME_Command; -.. code-block:: c +.. raw:: latex - extern rtems_shell_cmd_t rtems_shell_DNAME_Command; + \clearpage .. _pthread: @@ -1368,48 +1324,41 @@ pthread - display information about POSIX threads ------------------------------------------------- .. index:: pthread -**SYNOPSYS:** - -.. code-block:: shell - - pthread [id [id ...]] - -**DESCRIPTION:** - -When invoked with no arguments, this command prints information on the set of -POSIX API threads currently active in the system. - -If invoked with a set of ids as arguments, then just those objects are included -in the information printed. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. +SYNOPSYS: + .. code-block:: shell -**NOTES:** + pthread [id [id ...]] -This command is only available when the POSIX API is configured. +DESCRIPTION: + When invoked with no arguments, this command prints information on the set + of POSIX API threads currently active in the system. -**EXAMPLES:** + If invoked with a set of ids as arguments, then just those objects are + included in the information printed. -The following is an example of how to use the ``task`` on an application with -four POSIX threads: +EXIT STATUS: + This command returns 0 on success and non-zero if an error is encountered. -.. code-block:: shell +NOTES: + This command is only available when the POSIX API is configured. - SHLL [/] $ pthread - ID NAME PRI STATE MODES EVENTS WAITID WAITARG NOTES - ------------------------------------------------------------------------------ - 0b010002 Main 133 READY P:T:nA NONE 43010001 0x7b1148 - 0b010003 ISR 133 Wcvar P:T:nA NONE 43010003 0x7b1148 - 0b01000c 133 READY P:T:nA NONE 33010002 0x7b1148 - 0b01000d 133 Wmutex P:T:nA NONE 33010002 0x7b1148 +EXAMPLES: + The following is an example of how to use the ``task`` on an application + with four POSIX threads: -**CONFIGURATION:** + .. code-block:: shell -This command is part of the monitor commands which are always available in the -shell. + SHLL [/] $ pthread + ID NAME PRI STATE MODES EVENTS WAITID WAITARG NOTES + ------------------------------------------------------------------------------ + 0b010002 Main 133 READY P:T:nA NONE 43010001 0x7b1148 + 0b010003 ISR 133 Wcvar P:T:nA NONE 43010003 0x7b1148 + 0b01000c 133 READY P:T:nA NONE 33010002 0x7b1148 + 0b01000d 133 Wmutex P:T:nA NONE 33010002 0x7b1148 -**PROGRAMMING INFORMATION:** +CONFIGURATION: + This command is part of the monitor commands which are always available in + the shell. -This command is not directly available for invocation. +PROGRAMMING INFORMATION: + This command is not directly available for invocation. -- cgit v1.2.3