From 8ca13ed19f5b90bc53a7b2db26fb736d45e6007b Mon Sep 17 00:00:00 2001 From: Amar Takhar Date: Sat, 16 Jan 2016 15:32:09 -0500 Subject: Split document. --- shell/concept.rst | 3 + shell/configuration_and_init.rst | 381 ++ shell/file_and_directory.rst | 2656 ++++++++++++++ shell/function_and_variable.rst | 5 + shell/general_commands.rst | 1203 +++++++ shell/index.rst | 47 +- shell/memory_commands.rst | 613 ++++ shell/network_commands.rst | 633 ++++ shell/preface.rst | 113 + shell/rtems_specific_commands.rst | 1352 +++++++ shell/shell.rst | 6996 ------------------------------------ shell/shell_old_reference_only.rst | 6996 ++++++++++++++++++++++++++++++++++++ 12 files changed, 14001 insertions(+), 6997 deletions(-) create mode 100644 shell/concept.rst create mode 100644 shell/configuration_and_init.rst create mode 100644 shell/file_and_directory.rst create mode 100644 shell/function_and_variable.rst create mode 100644 shell/general_commands.rst create mode 100644 shell/memory_commands.rst create mode 100644 shell/network_commands.rst create mode 100644 shell/preface.rst create mode 100644 shell/rtems_specific_commands.rst delete mode 100644 shell/shell.rst create mode 100644 shell/shell_old_reference_only.rst (limited to 'shell') diff --git a/shell/concept.rst b/shell/concept.rst new file mode 100644 index 0000000..226ddbe --- /dev/null +++ b/shell/concept.rst @@ -0,0 +1,3 @@ +Concept Index +############# + diff --git a/shell/configuration_and_init.rst b/shell/configuration_and_init.rst new file mode 100644 index 0000000..ab66c92 --- /dev/null +++ b/shell/configuration_and_init.rst @@ -0,0 +1,381 @@ +Configuration and Initialization +################################ + +Introduction +============ + +This chapter provides information on how the application configures and +initializes the RTEMS shell. + +Configuration +============= + +The command set available to the application is user configurable. It is +configured using a mechanism similar to the ``confdefs.h`` mechanism used to +specify application configuration. + +In the simplest case, if the user wishes to configure a command set with all +commands available that are neither filesystem management (e.g. mounting, +formating, etc.) or network related, then the following is all that is +required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #include + +In a slightly more complex example, if the user wishes to include all +networking commands as well as support for mounting MS-DOS and NFS filesystems, +then the following is all that is required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #define CONFIGURE_SHELL_MOUNT_MSDOS + #define CONFIGURE_SHELL_MOUNT_NFS + #include + +Customizing the Command Set +--------------------------- + +The user can configure specific command sets by either building up the set from +individual commands or starting with a complete set and disabling individual +commands. Each command has two configuration macros associated with it. + +*CONFIGURE_SHELL_COMMAND_XXX* + Each command has a constant of this form which is defined when + building a command set by individually enabling specific + commands. + +*CONFIGURE_SHELL_NO_COMMAND_XXX* + In contrast, each command has a similar command which is + defined when the application is configuring a command set + by disabling specific commands in the set. + +Adding Custom Commands +---------------------- + +One of the design goals of the RTEMS Shell was to make it easy for a user to +add custom commands specific to their application. We believe this design goal +was accomplished. In order to add a custom command, the user is required to do +the following: + +- Provide a *main-style* function which implements the command. If that + command function uses a ``getopt`` related function to parse arguments, it + *MUST* use the reentrant form. + +- Provide a command definition structure of type ``rtems_shell_cmd_t``. + +- Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro. + +Custom aliases are configured similarly but the user only provides an alias +definition structure of type ``rtems_shell_alias_t`` and configures the alias +via the ``CONFIGURE_SHELL_USER_ALIASES`` macro. + +In the following example, we have implemented a custom command named +``usercmd`` which simply prints the arguments it was passed. We have also +provided an alias for ``usercmd`` named ``userecho``. + +.. code-block:: c + + #include + int main_usercmd(int argc, char **argv) + { + int i; + printf( "UserCommand: argc=%d\n", argc ); + for (i=0 ; i + +Notice in the above example, that the user wrote the*main* for their command +(e.g. ``main_usercmd``) which looks much like any other ``main()``. They then +defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which +describes that command. This command definition structure is registered into +the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS`` +to ``&Shell_USERCMD_Command``. + +Similarly, to add the ``userecho`` alias, the user provides the alias +definition structure named ``Shell_USERECHO_Alias`` and defines +``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias. + +The user can configure any number of commands and aliases in this manner. + +Initialization +============== + +The shell may be easily attached to a serial port or to the ``telnetd`` server. +This section describes how that is accomplished. + +Attached to a Serial Port +------------------------- + +Starting the shell attached to the console or a serial port is very simple. The +user invokes ``rtems_shell_init`` with parameters to indicate the +characteristics of the task that will be executing the shell including name, +stack size, and priority. The user also specifies the device that the shell is +to be attached to. + +This example is taken from the ``fileio`` sample test. This shell portion of +this test can be run on any target which provides a console with input and +output capabilities. It does not include any commands which cannot be +supported on all BSPs. The source code for this test is in +``testsuites/samples/fileio`` with the shell configuration in the ``init.c`` +file. + +.. code-block:: c + + #include + void start_shell(void) + { + printf(" =========================\n"); + printf(" starting shell\n"); + printf(" =========================\n"); + rtems_shell_init( + "SHLL", /* task name */ + RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */ + 100, /* task priority */ + "/dev/console", /* device name */ + false, /* run forever */ + true, /* wait for shell to terminate */ + rtems_shell_login_check /* login check function, + use NULL to disable a login check */ + ); + } + +In the above example, the call to ``rtems_shell_init`` spawns a task to run the +RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The +caller suspends itself and lets the shell take over the console device. When +the shell is exited by the user, then control returns to the caller. + +Attached to a Socket +-------------------- + +TBD + +Access Control +============== + +Login Checks +------------ + +Login checks are optional for the RTEMS shell and can be configured via a login +check handler passed to ``rtems_shell_init()``. One login check handler +is ``rtems_shell_login_check()``. + +Configuration Files +------------------- + +The following files are used by the login check handler +``rtems_shell_login_check()`` to validate a passphrase for a user and to set up +the user environment for the shell command execution. + +:file:`/etc/passwd` + The format for each line is + + .. code:: c + + user_name:password:UID:GID:GECOS:directory:shell + + with colon separated fields. For more information refer to the Linux + PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the + user. An empty password allows login without a password for this user. In + contrast to standard UNIX systems, this file is only readable and writeable + for the user with an UID of zero by default. The ``directory`` is used to + perform a filesystem change root operation in ``rtems_shell_login_check()`` + in contrast to a normal usage as the HOME directory of the user. + The *default* content is: + + .. code:: c + + root::0:0:::: + + so there is *no password required* for the ``root`` user. + +:file:`/etc/group` + The format for each line is: + + .. code:: c + + group_name:password:GID:user_list + + with colon separated fields. The ``user_list`` is comma separated. For + more information refer to the Linux GROUP(5) man page. In contrast to + standard UNIX systems, this file is only readable and writeable for the + user with an UID of zero by default. The default content is + + .. code:: c + + root::0: + +Command Visibility and Execution Permission +------------------------------------------- + +Each command has: + +- an owner, + +- a group, and + +- a read permission flag for the owner, the group and all other users, and + +- an execution permission flag for the owner, the group and all other + users. + +The read and write permission flags are stored in the command mode. The read +permission flags determine the visibility of the command for the current user. +The execution permission flags determine the ability to execute a command for +the current user. These command properties can be displayed and changed with +the: + +- ``cmdls``, + +- ``cmdchown``, and + +- ``cmdchmod`` + +commands. The access is determined by the effective UID, the effective GID and +the supplementary group IDs of the current user and follows the standard +filesystem access procedure. + +Add CRYPT(3) Formats +-------------------- + +By default the ``crypt_r()`` function used by ``rtems_shell_login_check()`` +supports only plain text passphrases. Use ``crypt_add_format()`` to add more +formats. The following formats are available out of the box: + +- ``crypt_md5_format``, + +- ``crypt_sha256_format``, and + +- ``crypt_sha512_format``. + +An example follows: + +.. index:: crypt_add_format + +.. code:: c + + #include + void add_formats( void ) + { + crypt_add_format( &crypt_md5_format ); + crypt_add_format( &crypt_sha512_format ); + } + +Functions +========= + +This section describes the Shell related C functions which are publicly +available related to initialization and configuration. + +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 + +others - to indicate a failure condition + +**DESCRIPTION:** + +This service creates a task with the specified characteristics to run the RTEMS +Shell attached to the specified ``devname``. + +.. note:: + + This method invokes the ``rtems_task_create`` and ``rtems_task_start`` + directives and as such may return any status code that those directives may + return. + + There is one POSIX key necessary for all shell instances together and one + POSIX key value pair per instance. You should make sure that your RTEMS + configuration accounts for these resources. + +rtems_shell_login_check - Default login check handler +----------------------------------------------------- +.. 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. + +**DESCRIPTION:** + +This function checks if the specified passphrase is valid for the specified +user. + +.. note:: + + As a side-effect if the specified passphrase is valid for the specified + user, this function: + + - performs a filesystem change root operation to the directory of the + specified user if the directory path is non-empty, + + - changes the owner of the current shell device to the UID of the specified + user, + + - 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 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. + diff --git a/shell/file_and_directory.rst b/shell/file_and_directory.rst new file mode 100644 index 0000000..23ec49e --- /dev/null +++ b/shell/file_and_directory.rst @@ -0,0 +1,2656 @@ +File and Directory Commands +########################### + +Introduction +============ + +The RTEMS shell has the following file and directory commands: + +- ``blksync`` - sync the block driver + +- ``cat`` - display file contents + +- ``cd`` - alias for chdir + +- ``chdir`` - change the current directory + +- ``chmod`` - change permissions of a file + +- ``chroot`` - change the root directory + +- ``cp`` - copy files + +- ``dd`` - format disks + +- ``debugrfs`` - debug RFS file system + +- ``df`` - display file system disk space usage + +- ``dir`` - alias for ls + +- ``fdisk`` - format disks + +- ``hexdump`` - format disks + +- ``ln`` - make links + +- ``ls`` - list files in the directory + +- ``md5`` - display file system disk space usage + +- ``mkdir`` - create a directory + +- ``mkdos`` - DOSFS disk format + +- ``mknod`` - make device special file + +- ``mkrfs`` - format RFS file system + +- ``mount`` - mount disk + +- ``mv`` - move files + +- ``pwd`` - print work directory + +- ``rmdir`` - remove empty directories + +- ``rm`` - remove files + +- ``umask`` - Set file mode creation mask + +- ``unmount`` - unmount disk + +Commands +======== + +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. + +blksync - sync the block driver +------------------------------- +.. index:: blksync + +**SYNOPSYS:** + +.. code:: c + + blksync driver + +**DESCRIPTION:** + +This command XXX + +**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 ``blksync``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_blksync + +The ``blksync`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_blksync( + int argc, + char \**argv + ); + +The configuration structure for the ``blksync`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command; + +cat - display file contents +--------------------------- +.. index:: cat + +**SYNOPSYS:** + +.. code:: c + + cat file1 \[file2 .. fileN] + +**DESCRIPTION:** + +This command displays the contents of the specified files. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +It is possible to read the input from a device file using ``cat``. + +**EXAMPLES:** + +The following is an example of how to use ``cat``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_cat + +The ``cat`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cat( + int argc, + char \**argv + ); + +The configuration structure for the ``cat`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CAT_Command; + +cd - alias for chdir +-------------------- +.. index:: cd + +**SYNOPSYS:** + +.. code:: c + + cd directory + +**DESCRIPTION:** + +This command is an alias or alternate name for the ``chdir``. +See `ls - list files in the directory`_ for more information. + +**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 ``cd``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_cd + +The ``cd`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cd( + int argc, + char \**argv + ); + +The configuration structure for the ``cd`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CD_Command; + + +chdir - change the current directory +------------------------------------ +.. index:: chdir + +**SYNOPSYS:** + +.. code:: c + + 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 ``/``. + +**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 ``chdir``: +.. code:: c + + SHLL \[/] $ pwd + / + SHLL \[/] $ chdir etc + SHLL \[/etc] $ pwd + /etc + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_chdir + +The ``chdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chdir( + int argc, + char \**argv + ); + +The configuration structure for the ``chdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHDIR_Command; + +chmod - change permissions of a file +------------------------------------ +.. index:: chmod + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_chmod + +The ``chmod`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chmod( + int argc, + char \**argv + ); + +The configuration structure for the ``chmod`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHMOD_Command; + +chroot - change the root directory +---------------------------------- +.. index:: chroot + +**SYNOPSYS:** + +.. code:: c + + chroot \[dir] + +**DESCRIPTION:** + +This command changes the root directory to ``dir`` for subsequent +commands. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +The destination directory ``dir`` must exist. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``chroot`` +and the impact it has on the environment for subsequent +command invocations: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_chroot + +The ``chroot`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chroot( + int argc, + char \**argv + ); + +The configuration structure for the ``chroot`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHROOT_Command; + +cp - copy files +--------------- +.. index:: cp + +**SYNOPSYS:** + +.. code:: c + + cp \[-R \[-H | -L | -P]] \[-f | -i] \[-pv] src target + cp \[-R \[-H | -L] ] \[-f | -i] \[-NpPv] source_file ... target_directory + +**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. + +The following options are available: + +*-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:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_main_cp + +The ``cp`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_main_cp( + int argc, + char \**argv + ); + +The configuration structure for the ``cp`` has the +following prototype: +.. code:: c + + 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. + +dd - convert and copy a file +---------------------------- +.. index:: dd + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + SHLL \[/] $ dd if=/nfs/boot-image of=/dev/hda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_dd + +The ``dd`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dd( + int argc, + char \**argv + ); + +The configuration structure for the ``dd`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DD_Command; + +debugrfs - debug RFS file system +-------------------------------- +.. index:: debugrfs + +**SYNOPSYS:** + +.. code:: c + + debugrfs \[-hl] path command \[options] + +**DESCRIPTION:** + +The command provides debugging information for the RFS file system. + +The options are: + +*-h* + Print a help message. + +*-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. + +The commands are: + +*block start \[end]* + Display the contents of the blocks from start to end. + +*data* + Display the file system data and configuration. + +*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. + +*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. + + *-e* + + Search and display on inodes that have an error. + + *-f* + + Force display of inodes, even when in error. + +**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 ``debugrfs``: +.. code:: c + + SHLL \[/] $ debugrfs /c data + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_debugrfs + +The ``debugrfs`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_debugrfs( + int argc, + char \**argv + ); + +The configuration structure for ``debugrfs`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command; + +df - display file system disk space usage +----------------------------------------- +.. index:: df + +**SYNOPSYS:** + +.. code:: c + + df \[-h] \[-B block_size] + +**DESCRIPTION:** + +This command print disk space usage for mounted file systems. + +**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 ``df``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_df + +The ``df`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_df( + int argc, + char \**argv + ); + +The configuration structure for the ``df`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DF_Command; + +dir - alias for ls +------------------ +.. index:: dir + +**SYNOPSYS:** + +.. code:: c + + dir \[dir] + +**DESCRIPTION:** + +This command is an alias or alternate name for the ``ls``. +See `ls - list files in the directory`_ +for more information. + +**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 ``dir``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_dir + +The ``dir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dir( + int argc, + char \**argv + ); + +The configuration structure for the ``dir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DIR_Command; + +fdisk - format disk +------------------- +.. index:: fdisk + +**SYNOPSYS:** + +.. code:: c + + fdisk + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all +shell commands have been configured. + +hexdump - ascii/dec/hex/octal dump +---------------------------------- +.. index:: hexdump + +**SYNOPSYS:** + +.. code:: c + + 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. + +*-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. + +*-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:: c + + SHLL \[/] $ hexdump -C -n 512 /dev/hda1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_hexdump + +The ``hexdump`` command is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_hexdump( + int argc, + char \**argv + ); + +The configuration structure for the ``hexdump`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command; + +ln - make links +--------------- +.. index:: ln + +**SYNOPSYS:** + +.. code:: 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: + +*-f* + Unlink any already existing file, permitting the link to occur. + +*-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. + +*-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.) + +*-n* + Same as -h, for compatibility with other ln implementations. + +*-s* + Create a symbolic link. + +*-v* + Cause ln to be verbose, showing files as they are processed. + +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. + +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. + +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. + +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. + +**EXIT STATUS:** + +The ``ln`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] ln -s /dev/console /dev/con1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ln + +The ``ln`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ln( + int argc, + char \**argv + ); + +The configuration structure for the ``ln`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LN_Command; + +**ORIGIN:** + +The implementation and portions of the documentation for this command +are from NetBSD 4.0. + +ls - list files in the directory +-------------------------------- +.. index:: ls + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``ls``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ls + +The ``ls`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ls( + int argc, + char \**argv + ); + +The configuration structure for the ``ls`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LS_Command; + +md5 - compute the Md5 hash of a file or list of files +----------------------------------------------------- +.. index:: md5 + +**SYNOPSYS:** + +.. code:: c + + 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``md5``: +.. code:: c + + SHLL \[/] $ md5 shell-init + MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_md5 + +The ``df`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_md5( + int argc, + char \**argv + ); + +The configuration structure for the ``md5`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MD5_Command; + +mkdir - create a directory +-------------------------- +.. index:: mkdir + +**SYNOPSYS:** + +.. code:: 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. + +**NOTES:** + +If this command is invoked with no arguments, nothing occurs. + +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``. + +**EXAMPLES:** + +The following is an example of how to use ``mkdir``: +.. code:: c + + 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 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_mkdir + +The ``mkdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkdir( + int argc, + char \**argv + ); + +The configuration structure for the ``mkdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKDIR_Command; + +mldos - DOSFS file system format +-------------------------------- +.. index:: pwd + +**SYNOPSYS:** + +.. code:: c + + mkdir \[-V label] \[-s sectors/cluster] \[-r size] \[-v] path + +**DESCRIPTION:** + +This command formats a block device entry with the DOSFS file system. + +*-V label* + +*-s sectors/cluster* + +*-r 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 ``mkdos``: +.. code:: c + + SHLL \[/] $ mkdos /dev/rda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_mkdos + +The ``mkdos`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkdos( + int argc, + char \**argv + ); + +The configuration structure for the ``mkdos`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKDOS_Command; + +mknod - make device special file +-------------------------------- +.. index:: mknod + +**SYNOPSYS:** + +.. code:: c + + 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. + +*-R* + Replace an existing file if its type is incorrect. Correct the + mode, user and group. + +*-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. + +*-m mode* + Specify the mode for the device node. The mode may be absolute or + symbolic, see *chmod*. + +*-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. + +*name* + Device name, for example “tty” for a termios serial device or “hd” + for a disk. + +*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. + +*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. + +*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. + +*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). + +*number* + A single opaque device number. Useful for netbooted computers which + require device numbers packed in a format that isn’t supported by + -F. + +**EXIT STATUS:** + +The ``mknod`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] mknod c 3 0 /dev/ttyS10 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mknod + +The ``mknod`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mknod( + int argc, + char \**argv + ); + +The configuration structure for the ``mknod`` has the following +prototype: +.. code:: c + + 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. + +mkrfs - format RFS file system +------------------------------ +.. index:: mkrfs + +**SYNOPSYS:** + +.. code:: c + + mkrfs \[-vsbiIo] device + +**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 following options are provided: + +*-v* + Display configuration and progress of the format. + +*-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. + +*-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. + +*-o* + Integer percentage of the media used by inodes. The default is 1%. + +*device* + Path of the device to format. + +**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 ``mkrfs``: +.. code:: c + + SHLL \[/] $ mkrfs /dev/fdda + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mkrfs + +The ``mkrfs`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkrfs( + int argc, + char \**argv + ); + +The configuration structure for ``mkrfs`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKRFS_Command; + +mount - mount disk +------------------ +.. index:: mount + +**SYNOPSYS:** + +.. code:: c + + mount \[-t fstype] \[-r] \[-L] device path + +**DESCRIPTION:** + +The ``mount`` command will mount a block device to a mount point +using the specified file system. The files systems are: + +- msdos - MSDOS File System + +- tftp - TFTP Network File System + +- ftp - FTP Network File System + +- nfs - Network File System + +- rfs - RTEMS 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. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +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. + +**EXAMPLES:** + +Mount the Flash Disk driver to the ’/fd’ mount point: +.. code:: c + + SHLL \[/] $ mount -t msdos /dev/flashdisk0 /fd + +Mount the NFS file system exported path ’bar’ by host ’foo’: +.. code:: c + + $ mount -t nfs foo:/bar /nfs + +Mount the TFTP file system on ’/tftp’: +.. code:: c + + $ mount -t tftp /tftp + +To access the TFTP files on server ’10.10.10.10’: +.. code:: c + + $ cat /tftp/10.10.10.10/test.txt + +**CONFIGURATION:** + +.. 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. + +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: + +- msdos - CONFIGURE_SHELL_MOUNT_MSDOS + +- tftp - CONFIGURE_SHELL_MOUNT_TFTP + +- ftp - CONFIGURE_SHELL_MOUNT_FTP + +- nfs - CONFIGURE_SHELL_MOUNT_NFS + +- rfs - CONFIGURE_SHELL_MOUNT_RFS + +An example configuration is: +.. code:: c + + #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 + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mount + +The ``mount`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mount( + int argc, + char \**argv + ); + +The configuration structure for the ``mount`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MOUNT_Command; + +mv - move files +--------------- +.. index:: mv + +**SYNOPSYS:** + +.. code:: c + + mv \[-fiv] source_file target_file + mv \[-fiv] source_file... target_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. + +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. + +The following options are available: + +*-f* + Do not prompt for confirmation before overwriting the destination + path. + +*-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. + +It is an error for the source operand to specify a directory if the +target exists and is not a directory. + +If the destination path does not have a mode which permits writing, mv +prompts the user for confirmation as specified for the -i option. + +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: +.. code:: c + + rm -f destination_path && \\ + cp -PRp source_file destination_path && \\ + rm -rf source_file + +**EXIT STATUS:** + +The ``mv`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] mv /dev/console /dev/con1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_main_mv + +The ``mv`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_main_mv( + int argc, + char \**argv + ); + +The configuration structure for the ``mv`` has the +following prototype: +.. code:: c + + 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. + +pwd - print work directory +-------------------------- +.. index:: pwd + +**SYNOPSYS:** + +.. code:: c + + pwd + +**DESCRIPTION:** + +This command prints the fully qualified filename of the current +working directory. + +**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 ``pwd``: +.. code:: c + + SHLL \[/] $ pwd + / + SHLL \[/] $ cd dev + SHLL \[/dev] $ pwd + /dev + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_pwd + +The ``pwd`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_pwd( + int argc, + char \**argv + ); + +The configuration structure for the ``pwd`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PWD_Command; + +rmdir - remove empty directories +-------------------------------- +.. index:: rmdir + +**SYNOPSYS:** + +.. code:: c + + rmdir \[dir1 .. dirN] + +**DESCRIPTION:** + +This command removes the specified set of directories. If no +directories are provided on the command line, no actions are taken. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +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``: +.. code:: c + + SHLL \[/] # mkdir joeldir + SHLL \[/] # rmdir joeldir + SHLL \[/] # ls joeldir + joeldir: No such file or directory. + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_rmdir + +The ``rmdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_rmdir( + int argc, + char \**argv + ); + +The configuration structure for the ``rmdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_RMDIR_Command; + +rm - remove files +----------------- +.. index:: rm + +**SYNOPSYS:** + +.. code:: c + + rm file1 \[file2 ... fileN] + +**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. + +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. + +**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 ``rm``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_main_rm + +The ``rm`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_rm( + int argc, + char \**argv + ); + +The configuration structure for the ``rm`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_RM_Command; + +umask - set file mode creation mask +----------------------------------- +.. index:: umask + +**SYNOPSYS:** + +.. code:: c + + umask \[new_umask] + +**DESCRIPTION:** + +This command sets the user file creation mask to ``new_umask``. The +argument ``new_umask`` may be octal, hexadecimal, or decimal. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This command does not currently support symbolic mode masks. + +**EXAMPLES:** + +The following is an example of how to use ``umask``: +.. code:: c + + SHLL \[/] $ umask + 022 + SHLL \[/] $ umask 0666 + 0666 + SHLL \[/] $ umask + 0666 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_umask + +The ``umask`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_umask( + int argc, + char \**argv + ); + +The configuration structure for the ``umask`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UMASK_Command; + +unmount - unmount disk +---------------------- +.. index:: unmount + +**SYNOPSYS:** + +.. code:: c + + unmount path + +**DESCRIPTION:** + +This command unmounts the device at the specified ``path``. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +TBD - Surely there must be some warnings to go here. + +**EXAMPLES:** + +The following is an example of how to use ``unmount``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_unmount + +The ``unmount`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_unmount( + int argc, + char \**argv + ); + +The configuration structure for the ``unmount`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command; + +.. COMMENT: COPYRIGHT (c) 1988-2012. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + diff --git a/shell/function_and_variable.rst b/shell/function_and_variable.rst new file mode 100644 index 0000000..b33a3b2 --- /dev/null +++ b/shell/function_and_variable.rst @@ -0,0 +1,5 @@ +Function and Variable Index +########################### + +.. COMMENT: There are currently no Command and Variable Index entries. + diff --git a/shell/general_commands.rst b/shell/general_commands.rst new file mode 100644 index 0000000..dd16f2a --- /dev/null +++ b/shell/general_commands.rst @@ -0,0 +1,1203 @@ +General Commands +################ + +Introduction +============ + +The RTEMS shell has the following general commands: + +- ``help`` - Print command help + +- ``alias`` - Add alias for an existing command + +- ``cmdls`` - List commands + +- ``cmdchown`` - Change user or owner of commands + +- ``cmdchmod`` - Change mode of commands + +- ``date`` - Print or set current date and time + +- ``echo`` - Produce message in a shell script + +- ``sleep`` - Delay for a specified amount of time + +- ``id`` - show uid gid euid and egid + +- ``tty`` - show ttyname + +- ``whoami`` - print effective user id + +- ``getenv`` - print environment variable + +- ``setenv`` - set environment variable + +- ``unsetenv`` - unset environment variable + +- ``time`` - time command execution + +- ``logoff`` - logoff from the system + +- ``rtc`` - RTC driver configuration + +- ``exit`` - alias for logoff command + +Commands +======== + +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. + +help - Print command help +------------------------- +.. index:: help + +**SYNOPSYS:** + +.. code:: c + + 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. + +alias - add alias for an existing command +----------------------------------------- +.. index:: alias + +**SYNOPSYS:** + +.. code:: c + + alias oldCommand newCommand + +**DESCRIPTION:** + +This command adds an alternate name for an existing command to the command set. + +**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 ``alias``: +.. code:: c + + SHLL \[/] $ me + shell:me command not found + SHLL \[/] $ alias whoami me + SHLL \[/] $ me + rtems + SHLL \[/] $ whoami + rtems + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_alias + +The ``alias`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_alias( + int argc, + char \**argv + ); + +The configuration structure for the ``alias`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ALIAS_Command; + +cmdls - List commands +--------------------- +.. index:: cmdls + +**SYNOPSYS:** + +.. code:: c + + cmdls COMMAND... + +**DESCRIPTION:** + +This command lists the visible commands of the command set. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +The current user must have read permission to list a command. + +**EXAMPLES:** + +The following is an example of how to use ``cmdls``: +.. code:: c + + SHLL \[/] # cmdls help shutdown + r-xr-xr-x 0 0 help + r-x------ 0 0 shutdown + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDLS_Command; + +cmdchown - Change user or owner of commands +------------------------------------------- +.. index:: cmdchown + +**SYNOPSYS:** + +.. code:: c + + cmdchown \[OWNER][:\[GROUP]] COMMAND... + +**DESCRIPTION:** + +This command changes the user or owner of a command. + +**EXIT STATUS:** + +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 +owner or group. + +**EXAMPLES:** + +The following is an example of how to use ``cmdchown``: +.. code:: c + + [/] # cmdls help + r-xr-xr-x 0 0 help + \[/] # cmdchown 1:1 help + \[/] # cmdls help + r--r--r-- 1 1 help + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command; + +cmdchmod - Change mode of commands +---------------------------------- +.. index:: cmdchmod + +**SYNOPSYS:** + +.. code:: c + + cmdchmod OCTAL-MODE COMMAND... + +**DESCRIPTION:** + +This command changes the mode of a command. + +**EXIT STATUS:** + +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. + +**EXAMPLES:** + +The following is an example of how to use ``cmdchmod``: +.. code:: c + + [/] # cmdls help + r-xr-xr-x 0 0 help + \[/] # cmdchmod 544 help + \[/] # cmdls help + r-xr--r-- 0 0 help + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command; + +date - print or set current date and time +----------------------------------------- +.. index:: date + +**SYNOPSYS:** + +.. code:: c + + 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. + +The ``date`` is specified in ``YYYY-MM-DD`` format. +The ``time`` is specified in ``HH:MM:SS`` format. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This comm + +**EXAMPLES:** + +The following is an example of how to use ``date``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_date + +The ``date`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_date( + int argc, + char \**argv + ); + +The configuration structure for the ``date`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DATE_Command; + +echo - produce message in a shell script +---------------------------------------- +.. index:: echo + +**SYNOPSYS:** + +.. code:: c + + 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. + +If any of the following sequences of characters is encountered during +output, the sequence is not output. Instead, the specified action is +performed: + +*\\b* + A backspace character is output. + +*\\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. + +*\\f* + Output a form feed. + +*\\n* + Output a newline character. + +*\\r* + Output a carriage return. + +*\\t* + Output a (horizontal) tab character. + +*\\v* + Output a vertical tab. + +*\\0digits* + Output the character whose value is given by zero to three digits. + If there are zero digits, a nul character is output. + +*\\\\* + Output a backslash. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +The octal character escape mechanism (\\0digits) differs from the C lan- +guage mechanism. + +There is no way to force ``echo`` to treat its arguments literally, rather +than interpreting them as options and escape sequences. + +**EXAMPLES:** + +The following is an example of how to use ``echo``: +.. code:: c + + SHLL \[/] $ echo a b c + a b c + SHLL \[/] $ echo + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_echo + +The ``echo`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_echo( + int argc, + char \**argv + ); + +The configuration structure for the ``echo`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ECHO_Command; + +**ORIGIN:** + +The implementation and portions of the documentation for this +command are from NetBSD 4.0. + +sleep - delay for a specified amount of time +-------------------------------------------- +.. index:: sleep + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This command is implemented using the ``nanosleep()`` method. + +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``. + +**EXAMPLES:** + +The following is an example of how to use ``sleep``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_sleep + +The ``sleep`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_sleep( + int argc, + char \**argv + ); + +The configuration structure for the ``sleep`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SLEEP_Command; + +id - show uid gid euid and egid +------------------------------- +.. index:: id + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**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. + +**EXAMPLES:** + +The first example of the ``id`` command is from a session logged +in as the normal user ``rtems``: +.. code:: c + + 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: +.. code:: c + + SHLL \[/] # id + uid=0(root),gid=0(root),euid=0(root),egid=0(root) + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_id + +The ``id`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_id( + int argc, + char \**argv + ); + +The configuration structure for the ``id`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ID_Command; + +tty - show ttyname +------------------ +.. index:: tty + +**SYNOPSYS:** + +.. code:: c + + tty + +**DESCRIPTION:** + +This command prints the file name of the device connected +to standard input. + +**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 ``tty``: +.. code:: c + + SHLL \[/] $ tty + /dev/console + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_tty + +The ``tty`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_tty( + int argc, + char \**argv + ); + +The configuration structure for the ``tty`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TTY_Command; + +whoami - print effective user id +-------------------------------- +.. index:: whoami + +**SYNOPSYS:** + +.. code:: c + + whoami + +**DESCRIPTION:** + +This command displays the user name associated with the current +effective user id. + +**EXIT STATUS:** + +This command always succeeds. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``whoami``: +.. code:: c + + SHLL \[/] $ whoami + rtems + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_whoami + +The ``whoami`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_whoami( + int argc, + char \**argv + ); + +The configuration structure for the ``whoami`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command; + +getenv - print environment variable +----------------------------------- +.. index:: getenv + +**SYNOPSYS:** + +.. code:: c + + getenv variable + +**DESCRIPTION:** + +This command is used to display the value of a ``variable`` in the set +of environment variables. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``getenv``: +.. code:: c + + SHLL \[/] $ getenv BASEPATH + /mnt/hda1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_getenv + +The ``getenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_getenv( + int argc, + char \**argv + ); + +The configuration structure for the ``getenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_GETENV_Command; + +setenv - set environment variable +--------------------------------- +.. index:: setenv + +**SYNOPSYS:** + +.. code:: c + + 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. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``setenv``: +.. code:: c + + SHLL \[/] $ setenv BASEPATH /mnt/hda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_setenv + +The ``setenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_setenv( + int argc, + char \**argv + ); + +The configuration structure for the ``setenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SETENV_Command; + +unsetenv - unset environment variable +------------------------------------- +.. index:: unsetenv + +**SYNOPSYS:** + +.. code:: c + + unsetenv variable + +**DESCRIPTION:** + +This command is remove to a ``variable`` from the set of environment +variables. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``unsetenv``: +.. code:: c + + SHLL \[/] $ unsetenv BASEPATH + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_unsetenv + +The ``unsetenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_unsetenv( + int argc, + char \**argv + ); + +The configuration structure for the ``unsetenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command; + +time - time command execution +----------------------------- +.. index:: time + +**SYNOPSYS:** + +.. code:: c + + time command \[argument ...] + +**DESCRIPTION:** + +The time command executes and times a command. After the command +finishes, time writes the total time elapsed. Times are reported in +seconds. + +**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 ``time``: +.. code:: c + + SHLL \[/] $ time cp -r /nfs/directory /c + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_time + +The ``time`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_time( + int argc, + char \**argv + ); + +The configuration structure for the ``time`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TIME_Command; + +logoff - logoff from the system +------------------------------- +.. index:: logoff + +**SYNOPSYS:** + +.. code:: c + + logoff + +**DESCRIPTION:** + +This command logs the user out of the shell. + +**EXIT STATUS:** + +This command does not return. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``logoff``: +.. code:: c + + SHLL \[/] $ logoff + logoff from the system... + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_logoff + +The ``logoff`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_logoff( + int argc, + char \**argv + ); + +The configuration structure for the ``logoff`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command; + +rtc - RTC driver configuration +------------------------------ +.. index:: rtc + +**SYNOPSYS:** + +.. code:: c + + rtc + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all +shell commands have been configured. + +exit - exit the shell +--------------------- +.. index:: exit + +**SYNOPSYS:** + +.. code:: c + + exit + +**DESCRIPTION:** + +This command causes the shell interpreter to ``exit``. + +**EXIT STATUS:** + +This command does not return. + +**NOTES:** + +In contrast to `logoff - logoff from the system`_, +this command is built into the shell interpreter loop. + +**EXAMPLES:** + +The following is an example of how to use ``exit``: +.. code:: c + + SHLL \[/] $ exit + Shell exiting + +**CONFIGURATION:** + +This command is always present and cannot be disabled. + +**PROGRAMMING INFORMATION:** + +The ``exit`` is implemented directly in the shell interpreter. +There is no C routine associated with it. + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + diff --git a/shell/index.rst b/shell/index.rst index ba1f551..3420f25 100644 --- a/shell/index.rst +++ b/shell/index.rst @@ -1 +1,46 @@ -.. include:: shell.rst +======================== +RTEMS Shell User’s Guide +======================== + +COPYRIGHT © 1988 - 2015. + +On-Line Applications Research Corporation (OAR). + +The authors have used their best efforts in preparing this material. These +efforts include the development, research, and testing of the theories and +programs to determine their effectiveness. No warranty of any kind, expressed +or implied, with regard to the software or the material contained in this +document is provided. No liability arising out of the application or use of +any product described in this document is assumed. The authors reserve the +right to revise this material and to make changes from time to time in the +content hereof without obligation to notify anyone of such revision or changes. + +The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning +RTEMS, its related support components, or its documentation should be directed +to the Community Project hosted at http://www.rtems.org/. + + +Table of Contents +----------------- + +.. toctree:: + + preface + + +.. toctree:: + :maxdepth: 3 + :numbered: + + configuration_and_init + general_commands + file_and_directory + memory_commands + rtems_specific_commands + network_commands + function_and_variable + concept + +* :ref:`genindex` +* :ref:`search` + diff --git a/shell/memory_commands.rst b/shell/memory_commands.rst new file mode 100644 index 0000000..0c80574 --- /dev/null +++ b/shell/memory_commands.rst @@ -0,0 +1,613 @@ +Memory Commands +############### + +Introduction +============ + +The RTEMS shell has the following memory commands: + +- ``mdump`` - Display contents of memory + +- ``wdump`` - Display contents of memory (word) + +- ``ldump`` - Display contents of memory (longword) + +- ``medit`` - Modify contents of memory + +- ``mfill`` - File memory with pattern + +- ``mmove`` - Move contents of memory + +- ``malloc`` - Obtain information on C Program Heap + +Commands +======== + +This section details the Memory 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. + +mdump - display contents of memory +---------------------------------- +.. index:: mdump + +**SYNOPSYS:** + +.. code:: c + + 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. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``mdump``: +.. code:: c + + 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 ..`....... ..(.. + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mdump + +The ``mdump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mdump( + int argc, + char \**argv + ); + +The configuration structure for the ``mdump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; + +wdump - display contents of memory (word) +----------------------------------------- +.. index:: wdump + +**SYNOPSYS:** + +.. code:: c + + 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``. + +When ``length`` is not provided, it defaults to ``320`` which +is twenty lines of output with eight words of output per line. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``wdump``: +.. code:: c + + SHLL \[/] $ wdump 0x02010000 32 + 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t + 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... + +**CONFIGURATION:** + +.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP +.. index:: CONFIGURE_SHELL_COMMAND_WDUMP + +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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_wdump + +The ``wdump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_wdump( + int argc, + char \**argv + ); + +The configuration structure for the ``wdump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; + +ldump - display contents of memory (longword) +--------------------------------------------- +.. index:: ldump + +**SYNOPSYS:** + +.. code:: c + + ldump \[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 4``. + +When ``length`` is not provided, it defaults to ``320`` which +is twenty lines of output with four longwords of output per line. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``ldump``: +.. code:: c + + SHLL \[/] $ ldump 0x02010000 32 + 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t + 0x02010010 020 0894 02010718-02010640 02010798 ............... + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ldump + +The ``ldump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ldump( + int argc, + char \**argv + ); + +The configuration structure for the ``ldump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; + +medit - modify contents of memory +--------------------------------- +.. index:: medit + +**SYNOPSYS:** + +.. code:: c + + medit address value1 \[value2 ... valueN] + +**DESCRIPTION:** + +This command is used to modify the contents of the memory starting +at ``address`` using the octets specified by the parameters``value1`` through ``valueN``. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``medit``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_medit + +The ``medit`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_medit( + int argc, + char \**argv + ); + +The configuration structure for the ``medit`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + +mfill - file memory with pattern +-------------------------------- +.. index:: mfill + +**SYNOPSYS:** + +.. code:: c + + mfill address length 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:** + +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. + +**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:: c + + 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:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mfill + +The ``mfill`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mfill( + int argc, + char \**argv + ); + +The configuration structure for the ``mfill`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MFILL_Command; + +mmove - move contents of memory +------------------------------- +.. index:: mmove + +**SYNOPSYS:** + +.. code:: c + + mmove dst src length + +**DESCRIPTION:** + +This command is used to copy the contents of the memory +starting at ``src`` to the memory located at ``dst`` +for the specified ``length`` in octets. + +**EXIT STATUS:** + +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 ``mmove``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mmove + +The ``mmove`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mmove( + int argc, + char \**argv + ); + +The configuration structure for the ``mmove`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; + +malloc - obtain information on C program heap +--------------------------------------------- +.. index:: malloc + +**SYNOPSYS:** + +.. code:: c + + 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: + +- Number of free blocks + +- Largest free block + +- Total bytes free + +- Number of used blocks + +- Largest used block + +- Total bytes used + +- Size of the allocatable area in bytes + +- Minimum free size ever in bytes + +- Maximum number of free blocks ever + +- Maximum number of blocks searched ever + +- Lifetime number of bytes allocated + +- Lifetime number of bytes freed + +- Total number of searches + +- Total number of successful allocations + +- Total number of failed allocations + +- Total number of successful frees + +- Total number of successful resizes + +When the subcommand ``walk`` is specified, then a heap walk will be +performed and information about each block is printed out. + +**EXIT STATUS:** + +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 the ``malloc`` command. +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_malloc + +The ``malloc`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_malloc( + int argc, + char \**argv + ); + +The configuration structure for the ``malloc`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + diff --git a/shell/network_commands.rst b/shell/network_commands.rst new file mode 100644 index 0000000..7778582 --- /dev/null +++ b/shell/network_commands.rst @@ -0,0 +1,633 @@ +Network Commands +################ + +Introduction +============ + +The RTEMS shell has the following network commands: + +- ``netstats`` - obtain network statistics + +- ``ifconfig`` - configure a network interface + +- ``route`` - show or manipulate the IP routing table + +- ``ping`` - ping a host or IP address + +Commands +======== + +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. + +netstats - obtain network statistics +------------------------------------ +.. index:: netstats + +**SYNOPSYS:** + +.. code:: c + + 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 + +*-u* + print UDP Statistics + +*-t* + print TCP Statistics + +**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 ``netstats``: + +The following is an example of using the ``netstats`` +command to print the IP routing table: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the MBUF statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the print the interface statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the print IP statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the ICMP statistics: +.. code:: c + + [/] $ 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:: c + + [/] $ netstats -u + \************ UDP Statistics \************ + +The following is an example of using the ``netstats`` +command to print the TCP statistics: +.. code:: c + + [/] $ 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:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_netstats + +The ``netstats`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_netstats( + int argc, + char \**argv + ); + +The configuration structure for the ``netstats`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; + +ifconfig - configure a network interface +---------------------------------------- +.. index:: ifconfig + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``ifconfig``: +.. code:: c + + ************ 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 + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ifconfig + +The ``ifconfig`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ifconfig( + int argc, + char \**argv + ); + +The configuration structure for the ``ifconfig`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; + +route - show or manipulate the ip routing table +----------------------------------------------- +.. index:: route + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:: c + + [/] $ 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_route + +The ``route`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_route( + int argc, + char \**argv + ); + +The configuration structure for the ``route`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + +ping - ping a host or IP address +-------------------------------- +.. index:: ping + +**SYNOPSYS:** + +.. code:: c + + 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. + +**EXAMPLES:** + +The following is an example of how to use ``oing`` to ping: +.. code:: c + + [/] # 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ping + +The ``ping`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ping( + int argc, + char \**argv + ); + +The configuration structure for the ``ping`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PING_Command; + diff --git a/shell/preface.rst b/shell/preface.rst new file mode 100644 index 0000000..5c32c07 --- /dev/null +++ b/shell/preface.rst @@ -0,0 +1,113 @@ +Preface +####### + +Real-time embedded systems vary widely based upon their operational and +maintenance requirements. Some of these systems provide ways for the user or +developer to interact with them. This interaction could be used for +operational, diagnostic, or configuration purposes. The capabilities described +in this manual are those provided with RTEMS to provide a command line +interface for user access. Some of these commands will be familiar as standard +POSIX utilities while others are RTEMS specific or helpful in debugging and +analyzing an embedded system. As a simple example of the powerful and very +familiar capabilities that the RTEMS Shell provides to an application, consider +the following example which hints at some of the capabilities available: + +.. code-block:: shell + + Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis) + COPYRIGHT (c) 1989-2011. + On-Line Applications Research Corporation (OAR). + Login into RTEMS + login: rtems + Password: + RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands. + SHLL [/] $ cat /etc/passwd + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false + SHLL [/] $ ls /dev + -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 + 2 files 0 bytes occupied + 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 6204 + 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 + SHLL [/] $ mount -L + File systems: msdos + SHLL [/] $ + +In the above example, the user *rtems* logs into a SPARC based RTEMS system. +The first command is ``cat /etc/passwd``. This simple command lets us know +that this application is running the In Memory File System (IMFS) and that the +infrastructure has provided dummy entries for */etc/passwd* and a few other +files. The contents of */etc/passwd* let us know that the user could have +logged in as ``root``. In fact, the ``root`` user has more permissions than +``rtems`` who is not allowed to write into the filesystem. + +The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style +device nodes which can be accesses through standard I/O function calls. + +The third command executed is the RTEMS specific ``stackuse`` which gives a +report on the stack usage of each thread in the system. Since stack overflows +are a common error in deeply embedded systems, this is a surprising simple, yet +powerful debugging aid. + +Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of +mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices +as well as network-based filesystens such as NFS and TFTP, the standard free +RTEMS provides a robuse infrastructure for embedded applications. + +This manual describes the RTEMS Shell and its command set. In our terminology, +the Shell is just a loop reading user input and turning that input into +commands with argument. The Shell provided with RTEMS is a simple command +reading loop with limited scripting capabilities. It can be connected to via a +standard serial port or connected to the RTEMS ``telnetd`` server for use across +a network. + +Each command in the command set is implemented as a single subroutine which has +a *main-style* prototype. The commands interpret their arguments and operate +upon stdin, stdout, and stderr by default. This allows each command to be +invoked independent of the shell. + +The described separation of shell from commands from communications mechanism +was an important design goal. At one level, the RTEMS Shell is a complete +shell environment providing access to multiple POSIX compliant filesystems and +TCP/IP stack. The subset of capabilities available is easy to configure and +the standard Shell can be logged into from either a serial port or via telnet. +But at another level, the Shell is a large set of components which can be +integrated into the user’s developed command interpreter. In either case, it +is trivial to add custom commands to the command set available. + +Acknowledgements +================ + +.. COMMENT: The RTEMS Project has been granted permission from The Open Group +.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents +.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide. +.. COMMENT: We have to include a specific acknowledgement paragraph in these +.. COMMENT: documents (e.g. preface or copyright page) and another slightly +.. COMMENT: different paragraph for each manual page that excerpts and uses +.. COMMENT: text from the standards. +.. COMMENT: This file should help ensure that the paragraphs are consistent +.. COMMENT: and not duplicated + +The Institute of Electrical and Electronics Engineers, Inc and The Open Group, +have given us permission to reprint portions of their documentation. + +.. pull-quote:: + + Portions of this text are reprinted and reproduced in electronic form from + IEEE Std 1003.1, 2004 Edition, Standard for Information Technology â + Operating System Interface (POSIX), The Open Group Base Specifications + Issue 6, Copyright © 2001-2004 by the Institute of Electrical and + Electronics Engineers, Inc and The Open Group. In the event of any + discrepancy between this version and the original IEEE and The Open Group + Standard, the original IEEE and The Open Group Standard is the referee + document. The original Standard can be obtained online at + http://www.opengroup.org/unix/online.html. This notice shall appear on any + product containing this material. + diff --git a/shell/rtems_specific_commands.rst b/shell/rtems_specific_commands.rst new file mode 100644 index 0000000..ccbb99b --- /dev/null +++ b/shell/rtems_specific_commands.rst @@ -0,0 +1,1352 @@ +RTEMS Specific Commands +####################### + +Introduction +============ + +The RTEMS shell has the following rtems commands: + +- ``shutdown`` - Shutdown the system + +- ``cpuuse`` - print or reset per thread cpu usage + +- ``stackuse`` - print per thread stack usage + +- ``perioduse`` - print or reset per period usage + +- ``profreport`` - print a profiling report + +- ``wkspace`` - Display information on Executive Workspace + +- ``config`` - Show the system configuration. + +- ``itask`` - List init tasks for the system + +- ``extension`` - Display information about extensions + +- ``task`` - Display information about tasks + +- ``queue`` - Display information about message queues + +- ``sema`` - display information about semaphores + +- ``region`` - display information about regions + +- ``part`` - display information about partitions + +- ``object`` - Display information about RTEMS objects + +- ``driver`` - Display the RTEMS device driver table + +- ``dname`` - Displays information about named drivers + +- ``pthread`` - Displays information about POSIX threads + +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. + +shutdown - Shutdown the system +------------------------------ +.. index:: shutdown + +**SYNOPSYS:** + +.. code:: c + + shutdown + +**DESCRIPTION:** + +This command is used to shutdown the RTEMS application. + +**EXIT STATUS:** + +This command does not return. + +**NOTES:** + +**EXAMPLES:** + +The following is an example of how to use ``shutdown``: +.. code:: c + + SHLL \[/] $ shutdown + System shutting down at user request + +The user will not see another prompt and the system will +shutdown. + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command; + +cpuuse - print or reset per thread cpu usage +-------------------------------------------- +.. index:: cpuuse + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_cpuuse + +The ``cpuuse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cpuuse( + int argc, + char \**argv + ); + +The configuration structure for the ``cpuuse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command; + +stackuse - print per thread stack usage +--------------------------------------- +.. index:: stackuse + +**SYNOPSYS:** + +.. code:: c + + stackuse + +**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:** + +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. + +**EXAMPLES:** + +The following is an example of how to use ``stackuse``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_stackuse + +The ``stackuse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_stackuse( + int argc, + char \**argv + ); + +The configuration structure for the ``stackuse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command; + +perioduse - print or reset per period usage +------------------------------------------- +.. index:: perioduse + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_perioduse + +The ``perioduse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_perioduse( + int argc, + char \**argv + ); + +The configuration structure for the ``perioduse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command; + +profreport - print a profiling report +------------------------------------- +.. index:: profreport + +**SYNOPSYS:** + +.. code:: c + + profreport + +**DESCRIPTION:** + +This command may be used to print a profiling report. + +**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:: c + + 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:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command; + +wkspace - display information on executive workspace +---------------------------------------------------- +.. index:: wkspace + +**SYNOPSYS:** + +.. code:: c + + wkspace + +**DESCRIPTION:** + +This command prints information on the current state of +the RTEMS Executive Workspace reported. This includes the +following information: + +- Number of free blocks + +- Largest free block + +- Total bytes free + +- Number of used blocks + +- Largest used block + +- Total bytes used + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``wkspace``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_wkspace + +The ``wkspace`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_wkspace( + int argc, + char \**argv + ); + +The configuration structure for the ``wkspace`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command; + +config - show the system configuration. +--------------------------------------- +.. index:: config + +**SYNOPSYS:** + +.. code:: c + + config + +**DESCRIPTION:** + +This command display information about the RTEMS Configuration. + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``config``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_config + +The ``config`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_config( + int argc, + char \**argv + ); + +The configuration structure for the ``config`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CONFIG_Command; + +itask - list init tasks for the system +-------------------------------------- +.. index:: itask + +**SYNOPSYS:** + +.. code:: c + + itask + +**DESCRIPTION:** + +This command prints a report on the set of initialization +tasks and threads in the system. + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**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:** + +The following is an example of how to use ``itask``: +.. code:: c + + SHLL \[/] $ itask + # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE + ------------------------------------------------------------------------------ + 0 UI1 \[0x2002258] 0 \[0x0] 1 nP DEFAULT 4096 \[0x1000] + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_itask + +The ``itask`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_itask( + int argc, + char \**argv + ); + +The configuration structure for the ``itask`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ITASK_Command; + +extension - display information about extensions +------------------------------------------------ +.. index:: extension + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 using the ``extension`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ extension + ID NAME + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_extension + +The ``extension`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_extension( + int argc, + char \**argv + ); + +The configuration structure for the ``extension`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command; + +task - display information about tasks +-------------------------------------- +.. index:: task + +**SYNOPSYS:** + +.. code:: c + + task \[id \[id ...] ] + +**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. + +**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 the ``task`` on an +application with just two Classic API tasks: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_task + +The ``task`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_task( + int argc, + char \**argv + ); + +The configuration structure for the ``task`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TASK_Command; + +queue - display information about message queues +------------------------------------------------ +.. index:: queue + +**SYNOPSYS:** + +.. code:: c + + queue \[id \[id ... ] ] + +**DESCRIPTION:** + +When invoked with no arguments, this command prints information on +the set of Classic API Message Queues 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of using the ``queue`` command +on a system with no Classic API Message Queues. +.. code:: c + + SHLL \[/] $ queue + ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_queue + +The ``queue`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_queue( + int argc, + char \**argv + ); + +The configuration structure for the ``queue`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_QUEUE_Command; + +sema - display information about semaphores +------------------------------------------- +.. index:: sema + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``sema``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_sema + +The ``sema`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_sema( + int argc, + char \**argv + ); + +The configuration structure for the ``sema`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SEMA_Command; + +region - display information about regions +------------------------------------------ +.. index:: region + +**SYNOPSYS:** + +.. code:: c + + region \[id \[id ... ] ] + +**DESCRIPTION:** + +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. + +**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 using the ``region`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ region + ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_region + +The ``region`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_region( + int argc, + char \**argv + ); + +The configuration structure for the ``region`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_REGION_Command; + +part - display information about partitions +------------------------------------------- +.. index:: part + +**SYNOPSYS:** + +.. code:: c + + part \[id \[id ... ] ] + +**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. + +**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 using the ``part`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ part + ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_part + +The ``part`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_part( + int argc, + char \**argv + ); + +The configuration structure for the ``part`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PART_Command; + +object - display information about rtems objects +------------------------------------------------ +.. index:: object + +**SYNOPSYS:** + +.. code:: c + + object \[id \[id ...] ] + +**DESCRIPTION:** + +When invoked with a set of object ids as arguments, then +a report on those objects is printed. + +**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 ``object``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_object + +The ``object`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_object( + int argc, + char \**argv + ); + +The configuration structure for the ``object`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_OBJECT_Command; + +driver - display the rtems device driver table +---------------------------------------------- +.. index:: driver + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``driver``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_driver + +The ``driver`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_driver( + int argc, + char \**argv + ); + +The configuration structure for the ``driver`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DRIVER_Command; + +dname - displays information about named drivers +------------------------------------------------ +.. index:: dname + +**SYNOPSYS:** + +.. code:: c + + dname + +**DESCRIPTION:** + +This command XXX + +WARNING! XXX 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``dname``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_dname + +The ``dname`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dname( + int argc, + char \**argv + ); + +The configuration structure for the ``dname`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DNAME_Command; + +pthread - display information about POSIX threads +------------------------------------------------- +.. index:: pthread + +**SYNOPSYS:** + +.. code:: c + + 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. + +**NOTES:** + +This command is only available when the POSIX API is configured. + +**EXAMPLES:** + +The following is an example of how to use the ``task`` on an +application with four POSIX threads: +.. code:: c + + 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 + +**CONFIGURATION:** + +This command is part of the monitor commands which are always +available in the shell. + +**PROGRAMMING INFORMATION:** + +This command is not directly available for invocation. + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + diff --git a/shell/shell.rst b/shell/shell.rst deleted file mode 100644 index 9e3b4b4..0000000 --- a/shell/shell.rst +++ /dev/null @@ -1,6996 +0,0 @@ -:orphan: - -.. COMMENT: COPYRIGHT (c) 1988-2013. -.. COMMENT: On-Line Applications Research Corporation (OAR). -.. COMMENT: All rights reserved. -.. COMMENT: -.. COMMENT: Master file for the Shell User's Guide -.. COMMENT: -.. COMMENT: COPYRIGHT (c) 1988-2002. - -======================== -RTEMS Shell User’s Guide -======================== - -COPYRIGHT © 1988 - 2015. - -On-Line Applications Research Corporation (OAR). - -The authors have used their best efforts in preparing this material. These -efforts include the development, research, and testing of the theories and -programs to determine their effectiveness. No warranty of any kind, expressed -or implied, with regard to the software or the material contained in this -document is provided. No liability arising out of the application or use of -any product described in this document is assumed. The authors reserve the -right to revise this material and to make changes from time to time in the -content hereof without obligation to notify anyone of such revision or changes. - -The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning -RTEMS, its related support components, or its documentation should be directed -to the Community Project hosted at http://www.rtems.org/. - -RTEMS Shell User’s Guide -######################## - -Preface -####### - -Real-time embedded systems vary widely based upon their operational and -maintenance requirements. Some of these systems provide ways for the user or -developer to interact with them. This interaction could be used for -operational, diagnostic, or configuration purposes. The capabilities described -in this manual are those provided with RTEMS to provide a command line -interface for user access. Some of these commands will be familiar as standard -POSIX utilities while others are RTEMS specific or helpful in debugging and -analyzing an embedded system. As a simple example of the powerful and very -familiar capabilities that the RTEMS Shell provides to an application, consider -the following example which hints at some of the capabilities available: - -.. code-block:: shell - - Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis) - COPYRIGHT (c) 1989-2011. - On-Line Applications Research Corporation (OAR). - Login into RTEMS - login: rtems - Password: - RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands. - SHLL [/] $ cat /etc/passwd - root:*:0:0:root::/:/bin/sh - rtems:*:1:1:RTEMS Application::/:/bin/sh - tty:!:2:2:tty owner::/:/bin/false - SHLL [/] $ ls /dev - -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 - 2 files 0 bytes occupied - 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 6204 - 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 - SHLL [/] $ mount -L - File systems: msdos - SHLL [/] $ - -In the above example, the user *rtems* logs into a SPARC based RTEMS system. -The first command is ``cat /etc/passwd``. This simple command lets us know -that this application is running the In Memory File System (IMFS) and that the -infrastructure has provided dummy entries for */etc/passwd* and a few other -files. The contents of */etc/passwd* let us know that the user could have -logged in as ``root``. In fact, the ``root`` user has more permissions than -``rtems`` who is not allowed to write into the filesystem. - -The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style -device nodes which can be accesses through standard I/O function calls. - -The third command executed is the RTEMS specific ``stackuse`` which gives a -report on the stack usage of each thread in the system. Since stack overflows -are a common error in deeply embedded systems, this is a surprising simple, yet -powerful debugging aid. - -Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of -mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices -as well as network-based filesystens such as NFS and TFTP, the standard free -RTEMS provides a robuse infrastructure for embedded applications. - -This manual describes the RTEMS Shell and its command set. In our terminology, -the Shell is just a loop reading user input and turning that input into -commands with argument. The Shell provided with RTEMS is a simple command -reading loop with limited scripting capabilities. It can be connected to via a -standard serial port or connected to the RTEMS ``telnetd`` server for use across -a network. - -Each command in the command set is implemented as a single subroutine which has -a *main-style* prototype. The commands interpret their arguments and operate -upon stdin, stdout, and stderr by default. This allows each command to be -invoked independent of the shell. - -The described separation of shell from commands from communications mechanism -was an important design goal. At one level, the RTEMS Shell is a complete -shell environment providing access to multiple POSIX compliant filesystems and -TCP/IP stack. The subset of capabilities available is easy to configure and -the standard Shell can be logged into from either a serial port or via telnet. -But at another level, the Shell is a large set of components which can be -integrated into the user’s developed command interpreter. In either case, it -is trivial to add custom commands to the command set available. - -Acknowledgements -================ - -.. COMMENT: The RTEMS Project has been granted permission from The Open Group -.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents -.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide. -.. COMMENT: We have to include a specific acknowledgement paragraph in these -.. COMMENT: documents (e.g. preface or copyright page) and another slightly -.. COMMENT: different paragraph for each manual page that excerpts and uses -.. COMMENT: text from the standards. -.. COMMENT: This file should help ensure that the paragraphs are consistent -.. COMMENT: and not duplicated - -The Institute of Electrical and Electronics Engineers, Inc and The Open Group, -have given us permission to reprint portions of their documentation. - -.. pull-quote:: - - Portions of this text are reprinted and reproduced in electronic form from - IEEE Std 1003.1, 2004 Edition, Standard for Information Technology â - Operating System Interface (POSIX), The Open Group Base Specifications - Issue 6, Copyright © 2001-2004 by the Institute of Electrical and - Electronics Engineers, Inc and The Open Group. In the event of any - discrepancy between this version and the original IEEE and The Open Group - Standard, the original IEEE and The Open Group Standard is the referee - document. The original Standard can be obtained online at - http://www.opengroup.org/unix/online.html. This notice shall appear on any - product containing this material. - -Configuration and Initialization -################################ - -Introduction -============ - -This chapter provides information on how the application configures and -initializes the RTEMS shell. - -Configuration -============= - -The command set available to the application is user configurable. It is -configured using a mechanism similar to the ``confdefs.h`` mechanism used to -specify application configuration. - -In the simplest case, if the user wishes to configure a command set with all -commands available that are neither filesystem management (e.g. mounting, -formating, etc.) or network related, then the following is all that is -required: - -.. code-block:: c - - #define CONFIGURE_SHELL_COMMANDS_INIT - #define CONFIGURE_SHELL_COMMANDS_ALL - #include - -In a slightly more complex example, if the user wishes to include all -networking commands as well as support for mounting MS-DOS and NFS filesystems, -then the following is all that is required: - -.. code-block:: c - - #define CONFIGURE_SHELL_COMMANDS_INIT - #define CONFIGURE_SHELL_COMMANDS_ALL - #define CONFIGURE_SHELL_MOUNT_MSDOS - #define CONFIGURE_SHELL_MOUNT_NFS - #include - -Customizing the Command Set ---------------------------- - -The user can configure specific command sets by either building up the set from -individual commands or starting with a complete set and disabling individual -commands. Each command has two configuration macros associated with it. - -*CONFIGURE_SHELL_COMMAND_XXX* - Each command has a constant of this form which is defined when - building a command set by individually enabling specific - commands. - -*CONFIGURE_SHELL_NO_COMMAND_XXX* - In contrast, each command has a similar command which is - defined when the application is configuring a command set - by disabling specific commands in the set. - -Adding Custom Commands ----------------------- - -One of the design goals of the RTEMS Shell was to make it easy for a user to -add custom commands specific to their application. We believe this design goal -was accomplished. In order to add a custom command, the user is required to do -the following: - -- Provide a *main-style* function which implements the command. If that - command function uses a ``getopt`` related function to parse arguments, it - *MUST* use the reentrant form. - -- Provide a command definition structure of type ``rtems_shell_cmd_t``. - -- Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro. - -Custom aliases are configured similarly but the user only provides an alias -definition structure of type ``rtems_shell_alias_t`` and configures the alias -via the ``CONFIGURE_SHELL_USER_ALIASES`` macro. - -In the following example, we have implemented a custom command named -``usercmd`` which simply prints the arguments it was passed. We have also -provided an alias for ``usercmd`` named ``userecho``. - -.. code-block:: c - - #include - int main_usercmd(int argc, char **argv) - { - int i; - printf( "UserCommand: argc=%d\n", argc ); - for (i=0 ; i - -Notice in the above example, that the user wrote the*main* for their command -(e.g. ``main_usercmd``) which looks much like any other ``main()``. They then -defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which -describes that command. This command definition structure is registered into -the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS`` -to ``&Shell_USERCMD_Command``. - -Similarly, to add the ``userecho`` alias, the user provides the alias -definition structure named ``Shell_USERECHO_Alias`` and defines -``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias. - -The user can configure any number of commands and aliases in this manner. - -Initialization -============== - -The shell may be easily attached to a serial port or to the ``telnetd`` server. -This section describes how that is accomplished. - -Attached to a Serial Port -------------------------- - -Starting the shell attached to the console or a serial port is very simple. The -user invokes ``rtems_shell_init`` with parameters to indicate the -characteristics of the task that will be executing the shell including name, -stack size, and priority. The user also specifies the device that the shell is -to be attached to. - -This example is taken from the ``fileio`` sample test. This shell portion of -this test can be run on any target which provides a console with input and -output capabilities. It does not include any commands which cannot be -supported on all BSPs. The source code for this test is in -``testsuites/samples/fileio`` with the shell configuration in the ``init.c`` -file. - -.. code-block:: c - - #include - void start_shell(void) - { - printf(" =========================\n"); - printf(" starting shell\n"); - printf(" =========================\n"); - rtems_shell_init( - "SHLL", /* task name */ - RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */ - 100, /* task priority */ - "/dev/console", /* device name */ - false, /* run forever */ - true, /* wait for shell to terminate */ - rtems_shell_login_check /* login check function, - use NULL to disable a login check */ - ); - } - -In the above example, the call to ``rtems_shell_init`` spawns a task to run the -RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The -caller suspends itself and lets the shell take over the console device. When -the shell is exited by the user, then control returns to the caller. - -Attached to a Socket --------------------- - -TBD - -Access Control -============== - -Login Checks ------------- - -Login checks are optional for the RTEMS shell and can be configured via a login -check handler passed to ``rtems_shell_init()``. One login check handler -is ``rtems_shell_login_check()``. - -Configuration Files -------------------- - -The following files are used by the login check handler -``rtems_shell_login_check()`` to validate a passphrase for a user and to set up -the user environment for the shell command execution. - -:file:`/etc/passwd` - The format for each line is - - .. code:: c - - user_name:password:UID:GID:GECOS:directory:shell - - with colon separated fields. For more information refer to the Linux - PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the - user. An empty password allows login without a password for this user. In - contrast to standard UNIX systems, this file is only readable and writeable - for the user with an UID of zero by default. The ``directory`` is used to - perform a filesystem change root operation in ``rtems_shell_login_check()`` - in contrast to a normal usage as the HOME directory of the user. - The *default* content is: - - .. code:: c - - root::0:0:::: - - so there is *no password required* for the ``root`` user. - -:file:`/etc/group` - The format for each line is: - - .. code:: c - - group_name:password:GID:user_list - - with colon separated fields. The ``user_list`` is comma separated. For - more information refer to the Linux GROUP(5) man page. In contrast to - standard UNIX systems, this file is only readable and writeable for the - user with an UID of zero by default. The default content is - - .. code:: c - - root::0: - -Command Visibility and Execution Permission -------------------------------------------- - -Each command has: - -- an owner, - -- a group, and - -- a read permission flag for the owner, the group and all other users, and - -- an execution permission flag for the owner, the group and all other - users. - -The read and write permission flags are stored in the command mode. The read -permission flags determine the visibility of the command for the current user. -The execution permission flags determine the ability to execute a command for -the current user. These command properties can be displayed and changed with -the: - -- ``cmdls``, - -- ``cmdchown``, and - -- ``cmdchmod`` - -commands. The access is determined by the effective UID, the effective GID and -the supplementary group IDs of the current user and follows the standard -filesystem access procedure. - -Add CRYPT(3) Formats --------------------- - -By default the ``crypt_r()`` function used by ``rtems_shell_login_check()`` -supports only plain text passphrases. Use ``crypt_add_format()`` to add more -formats. The following formats are available out of the box: - -- ``crypt_md5_format``, - -- ``crypt_sha256_format``, and - -- ``crypt_sha512_format``. - -An example follows: - -.. index:: crypt_add_format - -.. code:: c - - #include - void add_formats( void ) - { - crypt_add_format( &crypt_md5_format ); - crypt_add_format( &crypt_sha512_format ); - } - -Functions -========= - -This section describes the Shell related C functions which are publicly -available related to initialization and configuration. - -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 - -others - to indicate a failure condition - -**DESCRIPTION:** - -This service creates a task with the specified characteristics to run the RTEMS -Shell attached to the specified ``devname``. - -.. note:: - - This method invokes the ``rtems_task_create`` and ``rtems_task_start`` - directives and as such may return any status code that those directives may - return. - - There is one POSIX key necessary for all shell instances together and one - POSIX key value pair per instance. You should make sure that your RTEMS - configuration accounts for these resources. - -rtems_shell_login_check - Default login check handler ------------------------------------------------------ -.. 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. - -**DESCRIPTION:** - -This function checks if the specified passphrase is valid for the specified -user. - -.. note:: - - As a side-effect if the specified passphrase is valid for the specified - user, this function: - - - performs a filesystem change root operation to the directory of the - specified user if the directory path is non-empty, - - - changes the owner of the current shell device to the UID of the specified - user, - - - 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 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. - -General Commands -################ - -Introduction -============ - -The RTEMS shell has the following general commands: - -- ``help`` - Print command help - -- ``alias`` - Add alias for an existing command - -- ``cmdls`` - List commands - -- ``cmdchown`` - Change user or owner of commands - -- ``cmdchmod`` - Change mode of commands - -- ``date`` - Print or set current date and time - -- ``echo`` - Produce message in a shell script - -- ``sleep`` - Delay for a specified amount of time - -- ``id`` - show uid gid euid and egid - -- ``tty`` - show ttyname - -- ``whoami`` - print effective user id - -- ``getenv`` - print environment variable - -- ``setenv`` - set environment variable - -- ``unsetenv`` - unset environment variable - -- ``time`` - time command execution - -- ``logoff`` - logoff from the system - -- ``rtc`` - RTC driver configuration - -- ``exit`` - alias for logoff command - -Commands -======== - -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. - -help - Print command help -------------------------- -.. index:: help - -**SYNOPSYS:** - -.. code:: c - - 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. - -alias - add alias for an existing command ------------------------------------------ -.. index:: alias - -**SYNOPSYS:** - -.. code:: c - - alias oldCommand newCommand - -**DESCRIPTION:** - -This command adds an alternate name for an existing command to the command set. - -**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 ``alias``: -.. code:: c - - SHLL \[/] $ me - shell:me command not found - SHLL \[/] $ alias whoami me - SHLL \[/] $ me - rtems - SHLL \[/] $ whoami - rtems - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_alias - -The ``alias`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_alias( - int argc, - char \**argv - ); - -The configuration structure for the ``alias`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_ALIAS_Command; - -cmdls - List commands ---------------------- -.. index:: cmdls - -**SYNOPSYS:** - -.. code:: c - - cmdls COMMAND... - -**DESCRIPTION:** - -This command lists the visible commands of the command set. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -The current user must have read permission to list a command. - -**EXAMPLES:** - -The following is an example of how to use ``cmdls``: -.. code:: c - - SHLL \[/] # cmdls help shutdown - r-xr-xr-x 0 0 help - r-x------ 0 0 shutdown - -**CONFIGURATION:** - -.. 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. - -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: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CMDLS_Command; - -cmdchown - Change user or owner of commands -------------------------------------------- -.. index:: cmdchown - -**SYNOPSYS:** - -.. code:: c - - cmdchown \[OWNER][:\[GROUP]] COMMAND... - -**DESCRIPTION:** - -This command changes the user or owner of a command. - -**EXIT STATUS:** - -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 -owner or group. - -**EXAMPLES:** - -The following is an example of how to use ``cmdchown``: -.. code:: c - - [/] # cmdls help - r-xr-xr-x 0 0 help - \[/] # cmdchown 1:1 help - \[/] # cmdls help - r--r--r-- 1 1 help - -**CONFIGURATION:** - -.. 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. - -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: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command; - -cmdchmod - Change mode of commands ----------------------------------- -.. index:: cmdchmod - -**SYNOPSYS:** - -.. code:: c - - cmdchmod OCTAL-MODE COMMAND... - -**DESCRIPTION:** - -This command changes the mode of a command. - -**EXIT STATUS:** - -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. - -**EXAMPLES:** - -The following is an example of how to use ``cmdchmod``: -.. code:: c - - [/] # cmdls help - r-xr-xr-x 0 0 help - \[/] # cmdchmod 544 help - \[/] # cmdls help - r-xr--r-- 0 0 help - -**CONFIGURATION:** - -.. 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. - -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: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command; - -date - print or set current date and time ------------------------------------------ -.. index:: date - -**SYNOPSYS:** - -.. code:: c - - 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. - -The ``date`` is specified in ``YYYY-MM-DD`` format. -The ``time`` is specified in ``HH:MM:SS`` format. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -This comm - -**EXAMPLES:** - -The following is an example of how to use ``date``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_date - -The ``date`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_date( - int argc, - char \**argv - ); - -The configuration structure for the ``date`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DATE_Command; - -echo - produce message in a shell script ----------------------------------------- -.. index:: echo - -**SYNOPSYS:** - -.. code:: c - - 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. - -If any of the following sequences of characters is encountered during -output, the sequence is not output. Instead, the specified action is -performed: - -*\\b* - A backspace character is output. - -*\\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. - -*\\f* - Output a form feed. - -*\\n* - Output a newline character. - -*\\r* - Output a carriage return. - -*\\t* - Output a (horizontal) tab character. - -*\\v* - Output a vertical tab. - -*\\0digits* - Output the character whose value is given by zero to three digits. - If there are zero digits, a nul character is output. - -*\\\\* - Output a backslash. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -The octal character escape mechanism (\\0digits) differs from the C lan- -guage mechanism. - -There is no way to force ``echo`` to treat its arguments literally, rather -than interpreting them as options and escape sequences. - -**EXAMPLES:** - -The following is an example of how to use ``echo``: -.. code:: c - - SHLL \[/] $ echo a b c - a b c - SHLL \[/] $ echo - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_echo - -The ``echo`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_echo( - int argc, - char \**argv - ); - -The configuration structure for the ``echo`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_ECHO_Command; - -**ORIGIN:** - -The implementation and portions of the documentation for this -command are from NetBSD 4.0. - -sleep - delay for a specified amount of time --------------------------------------------- -.. index:: sleep - -**SYNOPSYS:** - -.. code:: c - - 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:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -This command is implemented using the ``nanosleep()`` method. - -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``. - -**EXAMPLES:** - -The following is an example of how to use ``sleep``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_sleep - -The ``sleep`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_sleep( - int argc, - char \**argv - ); - -The configuration structure for the ``sleep`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_SLEEP_Command; - -id - show uid gid euid and egid -------------------------------- -.. index:: id - -**SYNOPSYS:** - -.. code:: c - - 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:** - -This command returns 0 on success and non-zero if an error is encountered. - -**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. - -**EXAMPLES:** - -The first example of the ``id`` command is from a session logged -in as the normal user ``rtems``: -.. code:: c - - 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: -.. code:: c - - SHLL \[/] # id - uid=0(root),gid=0(root),euid=0(root),egid=0(root) - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_id - -The ``id`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_id( - int argc, - char \**argv - ); - -The configuration structure for the ``id`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_ID_Command; - -tty - show ttyname ------------------- -.. index:: tty - -**SYNOPSYS:** - -.. code:: c - - tty - -**DESCRIPTION:** - -This command prints the file name of the device connected -to standard input. - -**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 ``tty``: -.. code:: c - - SHLL \[/] $ tty - /dev/console - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_tty - -The ``tty`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_tty( - int argc, - char \**argv - ); - -The configuration structure for the ``tty`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_TTY_Command; - -whoami - print effective user id --------------------------------- -.. index:: whoami - -**SYNOPSYS:** - -.. code:: c - - whoami - -**DESCRIPTION:** - -This command displays the user name associated with the current -effective user id. - -**EXIT STATUS:** - -This command always succeeds. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``whoami``: -.. code:: c - - SHLL \[/] $ whoami - rtems - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_whoami - -The ``whoami`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_whoami( - int argc, - char \**argv - ); - -The configuration structure for the ``whoami`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command; - -getenv - print environment variable ------------------------------------ -.. index:: getenv - -**SYNOPSYS:** - -.. code:: c - - getenv variable - -**DESCRIPTION:** - -This command is used to display the value of a ``variable`` in the set -of environment variables. - -**EXIT STATUS:** - -This command will return 1 and print a diagnostic message if -a failure occurs. - -**NOTES:** - -The entire RTEMS application shares a single set of environment variables. - -**EXAMPLES:** - -The following is an example of how to use ``getenv``: -.. code:: c - - SHLL \[/] $ getenv BASEPATH - /mnt/hda1 - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_getenv - -The ``getenv`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_getenv( - int argc, - char \**argv - ); - -The configuration structure for the ``getenv`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_GETENV_Command; - -setenv - set environment variable ---------------------------------- -.. index:: setenv - -**SYNOPSYS:** - -.. code:: c - - 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. - -**EXIT STATUS:** - -This command will return 1 and print a diagnostic message if -a failure occurs. - -**NOTES:** - -The entire RTEMS application shares a single set of environment variables. - -**EXAMPLES:** - -The following is an example of how to use ``setenv``: -.. code:: c - - SHLL \[/] $ setenv BASEPATH /mnt/hda1 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_setenv - -The ``setenv`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_setenv( - int argc, - char \**argv - ); - -The configuration structure for the ``setenv`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_SETENV_Command; - -unsetenv - unset environment variable -------------------------------------- -.. index:: unsetenv - -**SYNOPSYS:** - -.. code:: c - - unsetenv variable - -**DESCRIPTION:** - -This command is remove to a ``variable`` from the set of environment -variables. - -**EXIT STATUS:** - -This command will return 1 and print a diagnostic message if -a failure occurs. - -**NOTES:** - -The entire RTEMS application shares a single set of environment variables. - -**EXAMPLES:** - -The following is an example of how to use ``unsetenv``: -.. code:: c - - SHLL \[/] $ unsetenv BASEPATH - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_unsetenv - -The ``unsetenv`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_unsetenv( - int argc, - char \**argv - ); - -The configuration structure for the ``unsetenv`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command; - -time - time command execution ------------------------------ -.. index:: time - -**SYNOPSYS:** - -.. code:: c - - time command \[argument ...] - -**DESCRIPTION:** - -The time command executes and times a command. After the command -finishes, time writes the total time elapsed. Times are reported in -seconds. - -**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 ``time``: -.. code:: c - - SHLL \[/] $ time cp -r /nfs/directory /c - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_time - -The ``time`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_time( - int argc, - char \**argv - ); - -The configuration structure for the ``time`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_TIME_Command; - -logoff - logoff from the system -------------------------------- -.. index:: logoff - -**SYNOPSYS:** - -.. code:: c - - logoff - -**DESCRIPTION:** - -This command logs the user out of the shell. - -**EXIT STATUS:** - -This command does not return. - -**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. - -**EXAMPLES:** - -The following is an example of how to use ``logoff``: -.. code:: c - - SHLL \[/] $ logoff - logoff from the system... - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_logoff - -The ``logoff`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_logoff( - int argc, - char \**argv - ); - -The configuration structure for the ``logoff`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command; - -rtc - RTC driver configuration ------------------------------- -.. index:: rtc - -**SYNOPSYS:** - -.. code:: c - - rtc - -**CONFIGURATION:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all -shell commands have been configured. - -exit - exit the shell ---------------------- -.. index:: exit - -**SYNOPSYS:** - -.. code:: c - - exit - -**DESCRIPTION:** - -This command causes the shell interpreter to ``exit``. - -**EXIT STATUS:** - -This command does not return. - -**NOTES:** - -In contrast to `logoff - logoff from the system`_, -this command is built into the shell interpreter loop. - -**EXAMPLES:** - -The following is an example of how to use ``exit``: -.. code:: c - - SHLL \[/] $ exit - Shell exiting - -**CONFIGURATION:** - -This command is always present and cannot be disabled. - -**PROGRAMMING INFORMATION:** - -The ``exit`` is implemented directly in the shell interpreter. -There is no C routine associated with it. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -File and Directory Commands -########################### - -Introduction -============ - -The RTEMS shell has the following file and directory commands: - -- ``blksync`` - sync the block driver - -- ``cat`` - display file contents - -- ``cd`` - alias for chdir - -- ``chdir`` - change the current directory - -- ``chmod`` - change permissions of a file - -- ``chroot`` - change the root directory - -- ``cp`` - copy files - -- ``dd`` - format disks - -- ``debugrfs`` - debug RFS file system - -- ``df`` - display file system disk space usage - -- ``dir`` - alias for ls - -- ``fdisk`` - format disks - -- ``hexdump`` - format disks - -- ``ln`` - make links - -- ``ls`` - list files in the directory - -- ``md5`` - display file system disk space usage - -- ``mkdir`` - create a directory - -- ``mkdos`` - DOSFS disk format - -- ``mknod`` - make device special file - -- ``mkrfs`` - format RFS file system - -- ``mount`` - mount disk - -- ``mv`` - move files - -- ``pwd`` - print work directory - -- ``rmdir`` - remove empty directories - -- ``rm`` - remove files - -- ``umask`` - Set file mode creation mask - -- ``unmount`` - unmount disk - -Commands -======== - -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. - -blksync - sync the block driver -------------------------------- -.. index:: blksync - -**SYNOPSYS:** - -.. code:: c - - blksync driver - -**DESCRIPTION:** - -This command XXX - -**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 ``blksync``: -.. code:: c - - EXAMPLE_TBD - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_blksync - -The ``blksync`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_blksync( - int argc, - char \**argv - ); - -The configuration structure for the ``blksync`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command; - -cat - display file contents ---------------------------- -.. index:: cat - -**SYNOPSYS:** - -.. code:: c - - cat file1 \[file2 .. fileN] - -**DESCRIPTION:** - -This command displays the contents of the specified files. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -It is possible to read the input from a device file using ``cat``. - -**EXAMPLES:** - -The following is an example of how to use ``cat``: -.. code:: c - - 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:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_cat - -The ``cat`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_cat( - int argc, - char \**argv - ); - -The configuration structure for the ``cat`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CAT_Command; - -cd - alias for chdir --------------------- -.. index:: cd - -**SYNOPSYS:** - -.. code:: c - - cd directory - -**DESCRIPTION:** - -This command is an alias or alternate name for the ``chdir``. -See `ls - list files in the directory`_ for more information. - -**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 ``cd``: -.. code:: c - - 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:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_cd - -The ``cd`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_cd( - int argc, - char \**argv - ); - -The configuration structure for the ``cd`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CD_Command; - - -chdir - change the current directory ------------------------------------- -.. index:: chdir - -**SYNOPSYS:** - -.. code:: c - - 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 ``/``. - -**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 ``chdir``: -.. code:: c - - SHLL \[/] $ pwd - / - SHLL \[/] $ chdir etc - SHLL \[/etc] $ pwd - /etc - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_chdir - -The ``chdir`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_chdir( - int argc, - char \**argv - ); - -The configuration structure for the ``chdir`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CHDIR_Command; - -chmod - change permissions of a file ------------------------------------- -.. index:: chmod - -**SYNOPSYS:** - -.. code:: c - - 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:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_chmod - -The ``chmod`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_chmod( - int argc, - char \**argv - ); - -The configuration structure for the ``chmod`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CHMOD_Command; - -chroot - change the root directory ----------------------------------- -.. index:: chroot - -**SYNOPSYS:** - -.. code:: c - - chroot \[dir] - -**DESCRIPTION:** - -This command changes the root directory to ``dir`` for subsequent -commands. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -The destination directory ``dir`` must exist. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``chroot`` -and the impact it has on the environment for subsequent -command invocations: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_chroot - -The ``chroot`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_chroot( - int argc, - char \**argv - ); - -The configuration structure for the ``chroot`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CHROOT_Command; - -cp - copy files ---------------- -.. index:: cp - -**SYNOPSYS:** - -.. code:: c - - cp \[-R \[-H | -L | -P]] \[-f | -i] \[-pv] src target - cp \[-R \[-H | -L] ] \[-f | -i] \[-NpPv] source_file ... target_directory - -**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. - -The following options are available: - -*-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:: c - - 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:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_main_cp - -The ``cp`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_main_cp( - int argc, - char \**argv - ); - -The configuration structure for the ``cp`` has the -following prototype: -.. code:: c - - 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. - -dd - convert and copy a file ----------------------------- -.. index:: dd - -**SYNOPSYS:** - -.. code:: c - - 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:: c - - SHLL \[/] $ dd if=/nfs/boot-image of=/dev/hda1 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_dd - -The ``dd`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_dd( - int argc, - char \**argv - ); - -The configuration structure for the ``dd`` has the following -prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DD_Command; - -debugrfs - debug RFS file system --------------------------------- -.. index:: debugrfs - -**SYNOPSYS:** - -.. code:: c - - debugrfs \[-hl] path command \[options] - -**DESCRIPTION:** - -The command provides debugging information for the RFS file system. - -The options are: - -*-h* - Print a help message. - -*-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. - -The commands are: - -*block start \[end]* - Display the contents of the blocks from start to end. - -*data* - Display the file system data and configuration. - -*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. - -*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. - - *-e* - - Search and display on inodes that have an error. - - *-f* - - Force display of inodes, even when in error. - -**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 ``debugrfs``: -.. code:: c - - SHLL \[/] $ debugrfs /c data - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_debugrfs - -The ``debugrfs`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_debugrfs( - int argc, - char \**argv - ); - -The configuration structure for ``debugrfs`` has the following -prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command; - -df - display file system disk space usage ------------------------------------------ -.. index:: df - -**SYNOPSYS:** - -.. code:: c - - df \[-h] \[-B block_size] - -**DESCRIPTION:** - -This command print disk space usage for mounted file systems. - -**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 ``df``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_df - -The ``df`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_main_df( - int argc, - char \**argv - ); - -The configuration structure for the ``df`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DF_Command; - -dir - alias for ls ------------------- -.. index:: dir - -**SYNOPSYS:** - -.. code:: c - - dir \[dir] - -**DESCRIPTION:** - -This command is an alias or alternate name for the ``ls``. -See `ls - list files in the directory`_ -for more information. - -**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 ``dir``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_dir - -The ``dir`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_dir( - int argc, - char \**argv - ); - -The configuration structure for the ``dir`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DIR_Command; - -fdisk - format disk -------------------- -.. index:: fdisk - -**SYNOPSYS:** - -.. code:: c - - fdisk - -**CONFIGURATION:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all -shell commands have been configured. - -hexdump - ascii/dec/hex/octal dump ----------------------------------- -.. index:: hexdump - -**SYNOPSYS:** - -.. code:: c - - 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. - -*-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. - -*-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:: c - - SHLL \[/] $ hexdump -C -n 512 /dev/hda1 - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_hexdump - -The ``hexdump`` command is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_hexdump( - int argc, - char \**argv - ); - -The configuration structure for the ``hexdump`` has the following -prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command; - -ln - make links ---------------- -.. index:: ln - -**SYNOPSYS:** - -.. code:: 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: - -*-f* - Unlink any already existing file, permitting the link to occur. - -*-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. - -*-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.) - -*-n* - Same as -h, for compatibility with other ln implementations. - -*-s* - Create a symbolic link. - -*-v* - Cause ln to be verbose, showing files as they are processed. - -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. - -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. - -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. - -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. - -**EXIT STATUS:** - -The ``ln`` utility exits 0 on success, and >0 if an error occurs. - -**NOTES:** - -NONE - -**EXAMPLES:** - -.. code:: c - - SHLL \[/] ln -s /dev/console /dev/con1 - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_ln - -The ``ln`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_ln( - int argc, - char \**argv - ); - -The configuration structure for the ``ln`` has the following -prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_LN_Command; - -**ORIGIN:** - -The implementation and portions of the documentation for this command -are from NetBSD 4.0. - -ls - list files in the directory --------------------------------- -.. index:: ls - -**SYNOPSYS:** - -.. code:: c - - 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:** - -This command returns 0 on success and non-zero if an error is encountered. - -**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. - -**EXAMPLES:** - -The following is an example of how to use ``ls``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_ls - -The ``ls`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_ls( - int argc, - char \**argv - ); - -The configuration structure for the ``ls`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_LS_Command; - -md5 - compute the Md5 hash of a file or list of files ------------------------------------------------------ -.. index:: md5 - -**SYNOPSYS:** - -.. code:: c - - 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. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``md5``: -.. code:: c - - SHLL \[/] $ md5 shell-init - MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_md5 - -The ``df`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_main_md5( - int argc, - char \**argv - ); - -The configuration structure for the ``md5`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MD5_Command; - -mkdir - create a directory --------------------------- -.. index:: mkdir - -**SYNOPSYS:** - -.. code:: 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. - -**NOTES:** - -If this command is invoked with no arguments, nothing occurs. - -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``. - -**EXAMPLES:** - -The following is an example of how to use ``mkdir``: -.. code:: c - - 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 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_mkdir - -The ``mkdir`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mkdir( - int argc, - char \**argv - ); - -The configuration structure for the ``mkdir`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MKDIR_Command; - -mldos - DOSFS file system format --------------------------------- -.. index:: pwd - -**SYNOPSYS:** - -.. code:: c - - mkdir \[-V label] \[-s sectors/cluster] \[-r size] \[-v] path - -**DESCRIPTION:** - -This command formats a block device entry with the DOSFS file system. - -*-V label* - -*-s sectors/cluster* - -*-r 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 ``mkdos``: -.. code:: c - - SHLL \[/] $ mkdos /dev/rda1 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_mkdos - -The ``mkdos`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mkdos( - int argc, - char \**argv - ); - -The configuration structure for the ``mkdos`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MKDOS_Command; - -mknod - make device special file --------------------------------- -.. index:: mknod - -**SYNOPSYS:** - -.. code:: c - - 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. - -*-R* - Replace an existing file if its type is incorrect. Correct the - mode, user and group. - -*-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. - -*-m mode* - Specify the mode for the device node. The mode may be absolute or - symbolic, see *chmod*. - -*-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. - -*name* - Device name, for example “tty” for a termios serial device or “hd” - for a disk. - -*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. - -*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. - -*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. - -*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). - -*number* - A single opaque device number. Useful for netbooted computers which - require device numbers packed in a format that isn’t supported by - -F. - -**EXIT STATUS:** - -The ``mknod`` utility exits 0 on success, and >0 if an error occurs. - -**NOTES:** - -NONE - -**EXAMPLES:** - -.. code:: c - - SHLL \[/] mknod c 3 0 /dev/ttyS10 - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mknod - -The ``mknod`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mknod( - int argc, - char \**argv - ); - -The configuration structure for the ``mknod`` has the following -prototype: -.. code:: c - - 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. - -mkrfs - format RFS file system ------------------------------- -.. index:: mkrfs - -**SYNOPSYS:** - -.. code:: c - - mkrfs \[-vsbiIo] device - -**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 following options are provided: - -*-v* - Display configuration and progress of the format. - -*-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. - -*-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. - -*-o* - Integer percentage of the media used by inodes. The default is 1%. - -*device* - Path of the device to format. - -**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 ``mkrfs``: -.. code:: c - - SHLL \[/] $ mkrfs /dev/fdda - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mkrfs - -The ``mkrfs`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mkrfs( - int argc, - char \**argv - ); - -The configuration structure for ``mkrfs`` has the following -prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MKRFS_Command; - -mount - mount disk ------------------- -.. index:: mount - -**SYNOPSYS:** - -.. code:: c - - mount \[-t fstype] \[-r] \[-L] device path - -**DESCRIPTION:** - -The ``mount`` command will mount a block device to a mount point -using the specified file system. The files systems are: - -- msdos - MSDOS File System - -- tftp - TFTP Network File System - -- ftp - FTP Network File System - -- nfs - Network File System - -- rfs - RTEMS 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. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -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. - -**EXAMPLES:** - -Mount the Flash Disk driver to the ’/fd’ mount point: -.. code:: c - - SHLL \[/] $ mount -t msdos /dev/flashdisk0 /fd - -Mount the NFS file system exported path ’bar’ by host ’foo’: -.. code:: c - - $ mount -t nfs foo:/bar /nfs - -Mount the TFTP file system on ’/tftp’: -.. code:: c - - $ mount -t tftp /tftp - -To access the TFTP files on server ’10.10.10.10’: -.. code:: c - - $ cat /tftp/10.10.10.10/test.txt - -**CONFIGURATION:** - -.. 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. - -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: - -- msdos - CONFIGURE_SHELL_MOUNT_MSDOS - -- tftp - CONFIGURE_SHELL_MOUNT_TFTP - -- ftp - CONFIGURE_SHELL_MOUNT_FTP - -- nfs - CONFIGURE_SHELL_MOUNT_NFS - -- rfs - CONFIGURE_SHELL_MOUNT_RFS - -An example configuration is: -.. code:: c - - #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 - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mount - -The ``mount`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mount( - int argc, - char \**argv - ); - -The configuration structure for the ``mount`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MOUNT_Command; - -mv - move files ---------------- -.. index:: mv - -**SYNOPSYS:** - -.. code:: c - - mv \[-fiv] source_file target_file - mv \[-fiv] source_file... target_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. - -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. - -The following options are available: - -*-f* - Do not prompt for confirmation before overwriting the destination - path. - -*-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. - -It is an error for the source operand to specify a directory if the -target exists and is not a directory. - -If the destination path does not have a mode which permits writing, mv -prompts the user for confirmation as specified for the -i option. - -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: -.. code:: c - - rm -f destination_path && \\ - cp -PRp source_file destination_path && \\ - rm -rf source_file - -**EXIT STATUS:** - -The ``mv`` utility exits 0 on success, and >0 if an error occurs. - -**NOTES:** - -NONE - -**EXAMPLES:** - -.. code:: c - - SHLL \[/] mv /dev/console /dev/con1 - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_main_mv - -The ``mv`` command is implemented by a C language function which -has the following prototype: -.. code:: c - - int rtems_shell_main_mv( - int argc, - char \**argv - ); - -The configuration structure for the ``mv`` has the -following prototype: -.. code:: c - - 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. - -pwd - print work directory --------------------------- -.. index:: pwd - -**SYNOPSYS:** - -.. code:: c - - pwd - -**DESCRIPTION:** - -This command prints the fully qualified filename of the current -working directory. - -**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 ``pwd``: -.. code:: c - - SHLL \[/] $ pwd - / - SHLL \[/] $ cd dev - SHLL \[/dev] $ pwd - /dev - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_pwd - -The ``pwd`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_pwd( - int argc, - char \**argv - ); - -The configuration structure for the ``pwd`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_PWD_Command; - -rmdir - remove empty directories --------------------------------- -.. index:: rmdir - -**SYNOPSYS:** - -.. code:: c - - rmdir \[dir1 .. dirN] - -**DESCRIPTION:** - -This command removes the specified set of directories. If no -directories are provided on the command line, no actions are taken. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -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``: -.. code:: c - - SHLL \[/] # mkdir joeldir - SHLL \[/] # rmdir joeldir - SHLL \[/] # ls joeldir - joeldir: No such file or directory. - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_rmdir - -The ``rmdir`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_rmdir( - int argc, - char \**argv - ); - -The configuration structure for the ``rmdir`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_RMDIR_Command; - -rm - remove files ------------------ -.. index:: rm - -**SYNOPSYS:** - -.. code:: c - - rm file1 \[file2 ... fileN] - -**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. - -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. - -**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 ``rm``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_main_rm - -The ``rm`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_main_rm( - int argc, - char \**argv - ); - -The configuration structure for the ``rm`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_RM_Command; - -umask - set file mode creation mask ------------------------------------ -.. index:: umask - -**SYNOPSYS:** - -.. code:: c - - umask \[new_umask] - -**DESCRIPTION:** - -This command sets the user file creation mask to ``new_umask``. The -argument ``new_umask`` may be octal, hexadecimal, or decimal. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -This command does not currently support symbolic mode masks. - -**EXAMPLES:** - -The following is an example of how to use ``umask``: -.. code:: c - - SHLL \[/] $ umask - 022 - SHLL \[/] $ umask 0666 - 0666 - SHLL \[/] $ umask - 0666 - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_umask - -The ``umask`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_umask( - int argc, - char \**argv - ); - -The configuration structure for the ``umask`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_UMASK_Command; - -unmount - unmount disk ----------------------- -.. index:: unmount - -**SYNOPSYS:** - -.. code:: c - - unmount path - -**DESCRIPTION:** - -This command unmounts the device at the specified ``path``. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -TBD - Surely there must be some warnings to go here. - -**EXAMPLES:** - -The following is an example of how to use ``unmount``: -.. code:: c - - EXAMPLE_TBD - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_unmount - -The ``unmount`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_unmount( - int argc, - char \**argv - ); - -The configuration structure for the ``unmount`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command; - -.. COMMENT: COPYRIGHT (c) 1988-2012. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -Memory Commands -############### - -Introduction -============ - -The RTEMS shell has the following memory commands: - -- ``mdump`` - Display contents of memory - -- ``wdump`` - Display contents of memory (word) - -- ``ldump`` - Display contents of memory (longword) - -- ``medit`` - Modify contents of memory - -- ``mfill`` - File memory with pattern - -- ``mmove`` - Move contents of memory - -- ``malloc`` - Obtain information on C Program Heap - -Commands -======== - -This section details the Memory 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. - -mdump - display contents of memory ----------------------------------- -.. index:: mdump - -**SYNOPSYS:** - -.. code:: c - - 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. - -When ``address`` is not provided, it defaults to ``0x00000000``. - -**EXIT STATUS:** - -This command always returns 0 to indicate success. - -**NOTES:** - -Dumping memory from a non-existent address may result in an unrecoverable -program fault. - -**EXAMPLES:** - -The following is an example of how to use ``mdump``: -.. code:: c - - 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 ..`....... ..(.. - -**CONFIGURATION:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all -shell commands have been configured. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mdump - -The ``mdump`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mdump( - int argc, - char \**argv - ); - -The configuration structure for the ``mdump`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; - -wdump - display contents of memory (word) ------------------------------------------ -.. index:: wdump - -**SYNOPSYS:** - -.. code:: c - - 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``. - -When ``length`` is not provided, it defaults to ``320`` which -is twenty lines of output with eight words of output per line. - -When ``address`` is not provided, it defaults to ``0x00000000``. - -**EXIT STATUS:** - -This command always returns 0 to indicate success. - -**NOTES:** - -Dumping memory from a non-existent address may result in an unrecoverable -program fault. - -**EXAMPLES:** - -The following is an example of how to use ``wdump``: -.. code:: c - - SHLL \[/] $ wdump 0x02010000 32 - 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t - 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... - -**CONFIGURATION:** - -.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP -.. index:: CONFIGURE_SHELL_COMMAND_WDUMP - -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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_wdump - -The ``wdump`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_wdump( - int argc, - char \**argv - ); - -The configuration structure for the ``wdump`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; - -ldump - display contents of memory (longword) ---------------------------------------------- -.. index:: ldump - -**SYNOPSYS:** - -.. code:: c - - ldump \[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 4``. - -When ``length`` is not provided, it defaults to ``320`` which -is twenty lines of output with four longwords of output per line. - -When ``address`` is not provided, it defaults to ``0x00000000``. - -**EXIT STATUS:** - -This command always returns 0 to indicate success. - -**NOTES:** - -Dumping memory from a non-existent address may result in an unrecoverable -program fault. - -**EXAMPLES:** - -The following is an example of how to use ``ldump``: -.. code:: c - - SHLL \[/] $ ldump 0x02010000 32 - 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t - 0x02010010 020 0894 02010718-02010640 02010798 ............... - -**CONFIGURATION:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all -shell commands have been configured. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_ldump - -The ``ldump`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_ldump( - int argc, - char \**argv - ); - -The configuration structure for the ``ldump`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; - -medit - modify contents of memory ---------------------------------- -.. index:: medit - -**SYNOPSYS:** - -.. code:: c - - medit address value1 \[value2 ... valueN] - -**DESCRIPTION:** - -This command is used to modify the contents of the memory starting -at ``address`` using the octets specified by the parameters``value1`` through ``valueN``. - -**EXIT STATUS:** - -This command returns 0 on success and non-zero if an error is encountered. - -**NOTES:** - -Dumping memory from a non-existent address may result in an unrecoverable -program fault. - -**EXAMPLES:** - -The following is an example of how to use ``medit``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_medit - -The ``medit`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_medit( - int argc, - char \**argv - ); - -The configuration structure for the ``medit`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; - -mfill - file memory with pattern --------------------------------- -.. index:: mfill - -**SYNOPSYS:** - -.. code:: c - - mfill address length 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:** - -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. - -**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:: c - - 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:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all -shell commands have been configured. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mfill - -The ``mfill`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mfill( - int argc, - char \**argv - ); - -The configuration structure for the ``mfill`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MFILL_Command; - -mmove - move contents of memory -------------------------------- -.. index:: mmove - -**SYNOPSYS:** - -.. code:: c - - mmove dst src length - -**DESCRIPTION:** - -This command is used to copy the contents of the memory -starting at ``src`` to the memory located at ``dst`` -for the specified ``length`` in octets. - -**EXIT STATUS:** - -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 ``mmove``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_mmove - -The ``mmove`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_mmove( - int argc, - char \**argv - ); - -The configuration structure for the ``mmove`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; - -malloc - obtain information on C program heap ---------------------------------------------- -.. index:: malloc - -**SYNOPSYS:** - -.. code:: c - - 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: - -- Number of free blocks - -- Largest free block - -- Total bytes free - -- Number of used blocks - -- Largest used block - -- Total bytes used - -- Size of the allocatable area in bytes - -- Minimum free size ever in bytes - -- Maximum number of free blocks ever - -- Maximum number of blocks searched ever - -- Lifetime number of bytes allocated - -- Lifetime number of bytes freed - -- Total number of searches - -- Total number of successful allocations - -- Total number of failed allocations - -- Total number of successful frees - -- Total number of successful resizes - -When the subcommand ``walk`` is specified, then a heap walk will be -performed and information about each block is printed out. - -**EXIT STATUS:** - -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 the ``malloc`` command. -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_malloc - -The ``malloc`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_malloc( - int argc, - char \**argv - ); - -The configuration structure for the ``malloc`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -RTEMS Specific Commands -####################### - -Introduction -============ - -The RTEMS shell has the following rtems commands: - -- ``shutdown`` - Shutdown the system - -- ``cpuuse`` - print or reset per thread cpu usage - -- ``stackuse`` - print per thread stack usage - -- ``perioduse`` - print or reset per period usage - -- ``profreport`` - print a profiling report - -- ``wkspace`` - Display information on Executive Workspace - -- ``config`` - Show the system configuration. - -- ``itask`` - List init tasks for the system - -- ``extension`` - Display information about extensions - -- ``task`` - Display information about tasks - -- ``queue`` - Display information about message queues - -- ``sema`` - display information about semaphores - -- ``region`` - display information about regions - -- ``part`` - display information about partitions - -- ``object`` - Display information about RTEMS objects - -- ``driver`` - Display the RTEMS device driver table - -- ``dname`` - Displays information about named drivers - -- ``pthread`` - Displays information about POSIX threads - -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. - -shutdown - Shutdown the system ------------------------------- -.. index:: shutdown - -**SYNOPSYS:** - -.. code:: c - - shutdown - -**DESCRIPTION:** - -This command is used to shutdown the RTEMS application. - -**EXIT STATUS:** - -This command does not return. - -**NOTES:** - -**EXAMPLES:** - -The following is an example of how to use ``shutdown``: -.. code:: c - - SHLL \[/] $ shutdown - System shutting down at user request - -The user will not see another prompt and the system will -shutdown. - -**CONFIGURATION:** - -.. 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. - -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: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command; - -cpuuse - print or reset per thread cpu usage --------------------------------------------- -.. index:: cpuuse - -**SYNOPSYS:** - -.. code:: c - - 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:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_cpuuse - -The ``cpuuse`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_cpuuse( - int argc, - char \**argv - ); - -The configuration structure for the ``cpuuse`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command; - -stackuse - print per thread stack usage ---------------------------------------- -.. index:: stackuse - -**SYNOPSYS:** - -.. code:: c - - stackuse - -**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:** - -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. - -**EXAMPLES:** - -The following is an example of how to use ``stackuse``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_stackuse - -The ``stackuse`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_stackuse( - int argc, - char \**argv - ); - -The configuration structure for the ``stackuse`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command; - -perioduse - print or reset per period usage -------------------------------------------- -.. index:: perioduse - -**SYNOPSYS:** - -.. code:: c - - 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:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_perioduse - -The ``perioduse`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_perioduse( - int argc, - char \**argv - ); - -The configuration structure for the ``perioduse`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command; - -profreport - print a profiling report -------------------------------------- -.. index:: profreport - -**SYNOPSYS:** - -.. code:: c - - profreport - -**DESCRIPTION:** - -This command may be used to print a profiling report. - -**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:: c - - 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:** - -.. 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. - -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: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command; - -wkspace - display information on executive workspace ----------------------------------------------------- -.. index:: wkspace - -**SYNOPSYS:** - -.. code:: c - - wkspace - -**DESCRIPTION:** - -This command prints information on the current state of -the RTEMS Executive Workspace reported. This includes the -following information: - -- Number of free blocks - -- Largest free block - -- Total bytes free - -- Number of used blocks - -- Largest used block - -- Total bytes used - -**EXIT STATUS:** - -This command always succeeds and returns 0. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``wkspace``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_wkspace - -The ``wkspace`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_wkspace( - int argc, - char \**argv - ); - -The configuration structure for the ``wkspace`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command; - -config - show the system configuration. ---------------------------------------- -.. index:: config - -**SYNOPSYS:** - -.. code:: c - - config - -**DESCRIPTION:** - -This command display information about the RTEMS Configuration. - -**EXIT STATUS:** - -This command always succeeds and returns 0. - -**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. - -**EXAMPLES:** - -The following is an example of how to use ``config``: -.. code:: c - - 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:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_config - -The ``config`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_config( - int argc, - char \**argv - ); - -The configuration structure for the ``config`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_CONFIG_Command; - -itask - list init tasks for the system --------------------------------------- -.. index:: itask - -**SYNOPSYS:** - -.. code:: c - - itask - -**DESCRIPTION:** - -This command prints a report on the set of initialization -tasks and threads in the system. - -**EXIT STATUS:** - -This command always succeeds and returns 0. - -**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:** - -The following is an example of how to use ``itask``: -.. code:: c - - SHLL \[/] $ itask - # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE - ------------------------------------------------------------------------------ - 0 UI1 \[0x2002258] 0 \[0x0] 1 nP DEFAULT 4096 \[0x1000] - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_itask - -The ``itask`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_itask( - int argc, - char \**argv - ); - -The configuration structure for the ``itask`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_ITASK_Command; - -extension - display information about extensions ------------------------------------------------- -.. index:: extension - -**SYNOPSYS:** - -.. code:: c - - 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. - -**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 using the ``extension`` command -on a system with no user extensions. -.. code:: c - - SHLL \[/] $ extension - ID NAME - ------------------------------------------------------------------------------ - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_extension - -The ``extension`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_extension( - int argc, - char \**argv - ); - -The configuration structure for the ``extension`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command; - -task - display information about tasks --------------------------------------- -.. index:: task - -**SYNOPSYS:** - -.. code:: c - - task \[id \[id ...] ] - -**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. - -**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 the ``task`` on an -application with just two Classic API tasks: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_task - -The ``task`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_task( - int argc, - char \**argv - ); - -The configuration structure for the ``task`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_TASK_Command; - -queue - display information about message queues ------------------------------------------------- -.. index:: queue - -**SYNOPSYS:** - -.. code:: c - - queue \[id \[id ... ] ] - -**DESCRIPTION:** - -When invoked with no arguments, this command prints information on -the set of Classic API Message Queues 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. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of using the ``queue`` command -on a system with no Classic API Message Queues. -.. code:: c - - SHLL \[/] $ queue - ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE - ------------------------------------------------------------------------------ - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_queue - -The ``queue`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_queue( - int argc, - char \**argv - ); - -The configuration structure for the ``queue`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_QUEUE_Command; - -sema - display information about semaphores -------------------------------------------- -.. index:: sema - -**SYNOPSYS:** - -.. code:: c - - 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. - -**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 ``sema``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_sema - -The ``sema`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_sema( - int argc, - char \**argv - ); - -The configuration structure for the ``sema`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_SEMA_Command; - -region - display information about regions ------------------------------------------- -.. index:: region - -**SYNOPSYS:** - -.. code:: c - - region \[id \[id ... ] ] - -**DESCRIPTION:** - -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. - -**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 using the ``region`` command -on a system with no user extensions. -.. code:: c - - SHLL \[/] $ region - ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS - ------------------------------------------------------------------------------ - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_region - -The ``region`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_region( - int argc, - char \**argv - ); - -The configuration structure for the ``region`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_REGION_Command; - -part - display information about partitions -------------------------------------------- -.. index:: part - -**SYNOPSYS:** - -.. code:: c - - part \[id \[id ... ] ] - -**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. - -**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 using the ``part`` command -on a system with no user extensions. -.. code:: c - - SHLL \[/] $ part - ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS - ------------------------------------------------------------------------------ - -**CONFIGURATION:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_part - -The ``part`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_part( - int argc, - char \**argv - ); - -The configuration structure for the ``part`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_PART_Command; - -object - display information about rtems objects ------------------------------------------------- -.. index:: object - -**SYNOPSYS:** - -.. code:: c - - object \[id \[id ...] ] - -**DESCRIPTION:** - -When invoked with a set of object ids as arguments, then -a report on those objects is printed. - -**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 ``object``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_object - -The ``object`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_object( - int argc, - char \**argv - ); - -The configuration structure for the ``object`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_OBJECT_Command; - -driver - display the rtems device driver table ----------------------------------------------- -.. index:: driver - -**SYNOPSYS:** - -.. code:: c - - 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. - -**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 ``driver``: -.. code:: c - - 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_driver - -The ``driver`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_driver( - int argc, - char \**argv - ); - -The configuration structure for the ``driver`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DRIVER_Command; - -dname - displays information about named drivers ------------------------------------------------- -.. index:: dname - -**SYNOPSYS:** - -.. code:: c - - dname - -**DESCRIPTION:** - -This command XXX - -WARNING! XXX 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. - -**NOTES:** - -NONE - -**EXAMPLES:** - -The following is an example of how to use ``dname``: -.. code:: c - - EXAMPLE_TBD - -**CONFIGURATION:** - -.. 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. - -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:** - -.. index:: rtems_shell_rtems_main_dname - -The ``dname`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_dname( - int argc, - char \**argv - ); - -The configuration structure for the ``dname`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_DNAME_Command; - -pthread - display information about POSIX threads -------------------------------------------------- -.. index:: pthread - -**SYNOPSYS:** - -.. code:: c - - 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. - -**NOTES:** - -This command is only available when the POSIX API is configured. - -**EXAMPLES:** - -The following is an example of how to use the ``task`` on an -application with four POSIX threads: -.. code:: c - - 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 - -**CONFIGURATION:** - -This command is part of the monitor commands which are always -available in the shell. - -**PROGRAMMING INFORMATION:** - -This command is not directly available for invocation. - -.. COMMENT: COPYRIGHT (c) 1988-2008. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -Network Commands -################ - -Introduction -============ - -The RTEMS shell has the following network commands: - -- ``netstats`` - obtain network statistics - -- ``ifconfig`` - configure a network interface - -- ``route`` - show or manipulate the IP routing table - -- ``ping`` - ping a host or IP address - -Commands -======== - -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. - -netstats - obtain network statistics ------------------------------------- -.. index:: netstats - -**SYNOPSYS:** - -.. code:: c - - 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 - -*-u* - print UDP Statistics - -*-t* - print TCP Statistics - -**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 ``netstats``: - -The following is an example of using the ``netstats`` -command to print the IP routing table: -.. code:: c - - [/] $ 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 - -The following is an example of using the ``netstats`` -command to print the MBUF statistics: -.. code:: c - - [/] $ 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 - -The following is an example of using the ``netstats`` -command to print the print the interface statistics: -.. code:: c - - [/] $ 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 - -The following is an example of using the ``netstats`` -command to print the print IP statistics: -.. code:: c - - [/] $ 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 - -The following is an example of using the ``netstats`` -command to print the ICMP statistics: -.. code:: c - - [/] $ 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:: c - - [/] $ netstats -u - \************ UDP Statistics \************ - -The following is an example of using the ``netstats`` -command to print the TCP statistics: -.. code:: c - - [/] $ 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:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all -shell commands have been configured. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_netstats - -The ``netstats`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_netstats( - int argc, - char \**argv - ); - -The configuration structure for the ``netstats`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; - -ifconfig - configure a network interface ----------------------------------------- -.. index:: ifconfig - -**SYNOPSYS:** - -.. code:: c - - 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. - -**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 ``ifconfig``: -.. code:: c - - ************ 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 - -**CONFIGURATION:** - -.. 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. - -This command can be excluded from the shell command set by -defining ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all -shell commands have been configured. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_ifconfig - -The ``ifconfig`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_ifconfig( - int argc, - char \**argv - ); - -The configuration structure for the ``ifconfig`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; - -route - show or manipulate the ip routing table ------------------------------------------------ -.. index:: route - -**SYNOPSYS:** - -.. code:: c - - 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:: c - - 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:: c - - [/] $ 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_route - -The ``route`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_route( - int argc, - char \**argv - ); - -The configuration structure for the ``route`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; - -ping - ping a host or IP address --------------------------------- -.. index:: ping - -**SYNOPSYS:** - -.. code:: c - - 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. - -**EXAMPLES:** - -The following is an example of how to use ``oing`` to ping: -.. code:: c - - [/] # 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:** - -.. 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. - -**PROGRAMMING INFORMATION:** - -.. index:: rtems_shell_rtems_main_ping - -The ``ping`` is implemented by a C language function -which has the following prototype: -.. code:: c - - int rtems_shell_rtems_main_ping( - int argc, - char \**argv - ); - -The configuration structure for the ``ping`` has the -following prototype: -.. code:: c - - extern rtems_shell_cmd_t rtems_shell_PING_Command; - -Function and Variable Index -########################### - -.. COMMENT: There are currently no Command and Variable Index entries. - -Concept Index -############# - -Command Index -############# - diff --git a/shell/shell_old_reference_only.rst b/shell/shell_old_reference_only.rst new file mode 100644 index 0000000..9e3b4b4 --- /dev/null +++ b/shell/shell_old_reference_only.rst @@ -0,0 +1,6996 @@ +:orphan: + +.. COMMENT: COPYRIGHT (c) 1988-2013. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. +.. COMMENT: +.. COMMENT: Master file for the Shell User's Guide +.. COMMENT: +.. COMMENT: COPYRIGHT (c) 1988-2002. + +======================== +RTEMS Shell User’s Guide +======================== + +COPYRIGHT © 1988 - 2015. + +On-Line Applications Research Corporation (OAR). + +The authors have used their best efforts in preparing this material. These +efforts include the development, research, and testing of the theories and +programs to determine their effectiveness. No warranty of any kind, expressed +or implied, with regard to the software or the material contained in this +document is provided. No liability arising out of the application or use of +any product described in this document is assumed. The authors reserve the +right to revise this material and to make changes from time to time in the +content hereof without obligation to notify anyone of such revision or changes. + +The RTEMS Project is hosted at http://www.rtems.org/. Any inquiries concerning +RTEMS, its related support components, or its documentation should be directed +to the Community Project hosted at http://www.rtems.org/. + +RTEMS Shell User’s Guide +######################## + +Preface +####### + +Real-time embedded systems vary widely based upon their operational and +maintenance requirements. Some of these systems provide ways for the user or +developer to interact with them. This interaction could be used for +operational, diagnostic, or configuration purposes. The capabilities described +in this manual are those provided with RTEMS to provide a command line +interface for user access. Some of these commands will be familiar as standard +POSIX utilities while others are RTEMS specific or helpful in debugging and +analyzing an embedded system. As a simple example of the powerful and very +familiar capabilities that the RTEMS Shell provides to an application, consider +the following example which hints at some of the capabilities available: + +.. code-block:: shell + + Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis) + COPYRIGHT (c) 1989-2011. + On-Line Applications Research Corporation (OAR). + Login into RTEMS + login: rtems + Password: + RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands. + SHLL [/] $ cat /etc/passwd + root:*:0:0:root::/:/bin/sh + rtems:*:1:1:RTEMS Application::/:/bin/sh + tty:!:2:2:tty owner::/:/bin/false + SHLL [/] $ ls /dev + -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 + 2 files 0 bytes occupied + 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 6204 + 0xffffffff INTR 0x023d2760 - 0x023d375f 0x00000000 4080 316 + SHLL [/] $ mount -L + File systems: msdos + SHLL [/] $ + +In the above example, the user *rtems* logs into a SPARC based RTEMS system. +The first command is ``cat /etc/passwd``. This simple command lets us know +that this application is running the In Memory File System (IMFS) and that the +infrastructure has provided dummy entries for */etc/passwd* and a few other +files. The contents of */etc/passwd* let us know that the user could have +logged in as ``root``. In fact, the ``root`` user has more permissions than +``rtems`` who is not allowed to write into the filesystem. + +The second command is ``ls /dev`` which lets us know that RTEMS has POSIX-style +device nodes which can be accesses through standard I/O function calls. + +The third command executed is the RTEMS specific ``stackuse`` which gives a +report on the stack usage of each thread in the system. Since stack overflows +are a common error in deeply embedded systems, this is a surprising simple, yet +powerful debugging aid. + +Finally, the last command, ``mount -L`` hints that RTEMS supports a variety of +mountable filesystems. With support for MS-DOS FAT on IDE/ATA and Flash devices +as well as network-based filesystens such as NFS and TFTP, the standard free +RTEMS provides a robuse infrastructure for embedded applications. + +This manual describes the RTEMS Shell and its command set. In our terminology, +the Shell is just a loop reading user input and turning that input into +commands with argument. The Shell provided with RTEMS is a simple command +reading loop with limited scripting capabilities. It can be connected to via a +standard serial port or connected to the RTEMS ``telnetd`` server for use across +a network. + +Each command in the command set is implemented as a single subroutine which has +a *main-style* prototype. The commands interpret their arguments and operate +upon stdin, stdout, and stderr by default. This allows each command to be +invoked independent of the shell. + +The described separation of shell from commands from communications mechanism +was an important design goal. At one level, the RTEMS Shell is a complete +shell environment providing access to multiple POSIX compliant filesystems and +TCP/IP stack. The subset of capabilities available is easy to configure and +the standard Shell can be logged into from either a serial port or via telnet. +But at another level, the Shell is a large set of components which can be +integrated into the user’s developed command interpreter. In either case, it +is trivial to add custom commands to the command set available. + +Acknowledgements +================ + +.. COMMENT: The RTEMS Project has been granted permission from The Open Group +.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents +.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide. +.. COMMENT: We have to include a specific acknowledgement paragraph in these +.. COMMENT: documents (e.g. preface or copyright page) and another slightly +.. COMMENT: different paragraph for each manual page that excerpts and uses +.. COMMENT: text from the standards. +.. COMMENT: This file should help ensure that the paragraphs are consistent +.. COMMENT: and not duplicated + +The Institute of Electrical and Electronics Engineers, Inc and The Open Group, +have given us permission to reprint portions of their documentation. + +.. pull-quote:: + + Portions of this text are reprinted and reproduced in electronic form from + IEEE Std 1003.1, 2004 Edition, Standard for Information Technology â + Operating System Interface (POSIX), The Open Group Base Specifications + Issue 6, Copyright © 2001-2004 by the Institute of Electrical and + Electronics Engineers, Inc and The Open Group. In the event of any + discrepancy between this version and the original IEEE and The Open Group + Standard, the original IEEE and The Open Group Standard is the referee + document. The original Standard can be obtained online at + http://www.opengroup.org/unix/online.html. This notice shall appear on any + product containing this material. + +Configuration and Initialization +################################ + +Introduction +============ + +This chapter provides information on how the application configures and +initializes the RTEMS shell. + +Configuration +============= + +The command set available to the application is user configurable. It is +configured using a mechanism similar to the ``confdefs.h`` mechanism used to +specify application configuration. + +In the simplest case, if the user wishes to configure a command set with all +commands available that are neither filesystem management (e.g. mounting, +formating, etc.) or network related, then the following is all that is +required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #include + +In a slightly more complex example, if the user wishes to include all +networking commands as well as support for mounting MS-DOS and NFS filesystems, +then the following is all that is required: + +.. code-block:: c + + #define CONFIGURE_SHELL_COMMANDS_INIT + #define CONFIGURE_SHELL_COMMANDS_ALL + #define CONFIGURE_SHELL_MOUNT_MSDOS + #define CONFIGURE_SHELL_MOUNT_NFS + #include + +Customizing the Command Set +--------------------------- + +The user can configure specific command sets by either building up the set from +individual commands or starting with a complete set and disabling individual +commands. Each command has two configuration macros associated with it. + +*CONFIGURE_SHELL_COMMAND_XXX* + Each command has a constant of this form which is defined when + building a command set by individually enabling specific + commands. + +*CONFIGURE_SHELL_NO_COMMAND_XXX* + In contrast, each command has a similar command which is + defined when the application is configuring a command set + by disabling specific commands in the set. + +Adding Custom Commands +---------------------- + +One of the design goals of the RTEMS Shell was to make it easy for a user to +add custom commands specific to their application. We believe this design goal +was accomplished. In order to add a custom command, the user is required to do +the following: + +- Provide a *main-style* function which implements the command. If that + command function uses a ``getopt`` related function to parse arguments, it + *MUST* use the reentrant form. + +- Provide a command definition structure of type ``rtems_shell_cmd_t``. + +- Configure that command using the ``CONFIGURE_SHELL_USER_COMMANDS`` macro. + +Custom aliases are configured similarly but the user only provides an alias +definition structure of type ``rtems_shell_alias_t`` and configures the alias +via the ``CONFIGURE_SHELL_USER_ALIASES`` macro. + +In the following example, we have implemented a custom command named +``usercmd`` which simply prints the arguments it was passed. We have also +provided an alias for ``usercmd`` named ``userecho``. + +.. code-block:: c + + #include + int main_usercmd(int argc, char **argv) + { + int i; + printf( "UserCommand: argc=%d\n", argc ); + for (i=0 ; i + +Notice in the above example, that the user wrote the*main* for their command +(e.g. ``main_usercmd``) which looks much like any other ``main()``. They then +defined a ``rtems_shell_cmd_t`` structure named ``Shell_USERCMD_Command`` which +describes that command. This command definition structure is registered into +the static command set by defining ``CONFIGURE_SHELL_USER_COMMANDS`` +to ``&Shell_USERCMD_Command``. + +Similarly, to add the ``userecho`` alias, the user provides the alias +definition structure named ``Shell_USERECHO_Alias`` and defines +``CONFIGURE_SHELL_USER_ALIASES`` to configure the alias. + +The user can configure any number of commands and aliases in this manner. + +Initialization +============== + +The shell may be easily attached to a serial port or to the ``telnetd`` server. +This section describes how that is accomplished. + +Attached to a Serial Port +------------------------- + +Starting the shell attached to the console or a serial port is very simple. The +user invokes ``rtems_shell_init`` with parameters to indicate the +characteristics of the task that will be executing the shell including name, +stack size, and priority. The user also specifies the device that the shell is +to be attached to. + +This example is taken from the ``fileio`` sample test. This shell portion of +this test can be run on any target which provides a console with input and +output capabilities. It does not include any commands which cannot be +supported on all BSPs. The source code for this test is in +``testsuites/samples/fileio`` with the shell configuration in the ``init.c`` +file. + +.. code-block:: c + + #include + void start_shell(void) + { + printf(" =========================\n"); + printf(" starting shell\n"); + printf(" =========================\n"); + rtems_shell_init( + "SHLL", /* task name */ + RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size */ + 100, /* task priority */ + "/dev/console", /* device name */ + false, /* run forever */ + true, /* wait for shell to terminate */ + rtems_shell_login_check /* login check function, + use NULL to disable a login check */ + ); + } + +In the above example, the call to ``rtems_shell_init`` spawns a task to run the +RTEMS Shell attached to ``/dev/console`` and executing at priority 100. The +caller suspends itself and lets the shell take over the console device. When +the shell is exited by the user, then control returns to the caller. + +Attached to a Socket +-------------------- + +TBD + +Access Control +============== + +Login Checks +------------ + +Login checks are optional for the RTEMS shell and can be configured via a login +check handler passed to ``rtems_shell_init()``. One login check handler +is ``rtems_shell_login_check()``. + +Configuration Files +------------------- + +The following files are used by the login check handler +``rtems_shell_login_check()`` to validate a passphrase for a user and to set up +the user environment for the shell command execution. + +:file:`/etc/passwd` + The format for each line is + + .. code:: c + + user_name:password:UID:GID:GECOS:directory:shell + + with colon separated fields. For more information refer to the Linux + PASSWD(5) man page. Use a ``password`` of ``*`` to disable the login of the + user. An empty password allows login without a password for this user. In + contrast to standard UNIX systems, this file is only readable and writeable + for the user with an UID of zero by default. The ``directory`` is used to + perform a filesystem change root operation in ``rtems_shell_login_check()`` + in contrast to a normal usage as the HOME directory of the user. + The *default* content is: + + .. code:: c + + root::0:0:::: + + so there is *no password required* for the ``root`` user. + +:file:`/etc/group` + The format for each line is: + + .. code:: c + + group_name:password:GID:user_list + + with colon separated fields. The ``user_list`` is comma separated. For + more information refer to the Linux GROUP(5) man page. In contrast to + standard UNIX systems, this file is only readable and writeable for the + user with an UID of zero by default. The default content is + + .. code:: c + + root::0: + +Command Visibility and Execution Permission +------------------------------------------- + +Each command has: + +- an owner, + +- a group, and + +- a read permission flag for the owner, the group and all other users, and + +- an execution permission flag for the owner, the group and all other + users. + +The read and write permission flags are stored in the command mode. The read +permission flags determine the visibility of the command for the current user. +The execution permission flags determine the ability to execute a command for +the current user. These command properties can be displayed and changed with +the: + +- ``cmdls``, + +- ``cmdchown``, and + +- ``cmdchmod`` + +commands. The access is determined by the effective UID, the effective GID and +the supplementary group IDs of the current user and follows the standard +filesystem access procedure. + +Add CRYPT(3) Formats +-------------------- + +By default the ``crypt_r()`` function used by ``rtems_shell_login_check()`` +supports only plain text passphrases. Use ``crypt_add_format()`` to add more +formats. The following formats are available out of the box: + +- ``crypt_md5_format``, + +- ``crypt_sha256_format``, and + +- ``crypt_sha512_format``. + +An example follows: + +.. index:: crypt_add_format + +.. code:: c + + #include + void add_formats( void ) + { + crypt_add_format( &crypt_md5_format ); + crypt_add_format( &crypt_sha512_format ); + } + +Functions +========= + +This section describes the Shell related C functions which are publicly +available related to initialization and configuration. + +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 + +others - to indicate a failure condition + +**DESCRIPTION:** + +This service creates a task with the specified characteristics to run the RTEMS +Shell attached to the specified ``devname``. + +.. note:: + + This method invokes the ``rtems_task_create`` and ``rtems_task_start`` + directives and as such may return any status code that those directives may + return. + + There is one POSIX key necessary for all shell instances together and one + POSIX key value pair per instance. You should make sure that your RTEMS + configuration accounts for these resources. + +rtems_shell_login_check - Default login check handler +----------------------------------------------------- +.. 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. + +**DESCRIPTION:** + +This function checks if the specified passphrase is valid for the specified +user. + +.. note:: + + As a side-effect if the specified passphrase is valid for the specified + user, this function: + + - performs a filesystem change root operation to the directory of the + specified user if the directory path is non-empty, + + - changes the owner of the current shell device to the UID of the specified + user, + + - 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 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. + +General Commands +################ + +Introduction +============ + +The RTEMS shell has the following general commands: + +- ``help`` - Print command help + +- ``alias`` - Add alias for an existing command + +- ``cmdls`` - List commands + +- ``cmdchown`` - Change user or owner of commands + +- ``cmdchmod`` - Change mode of commands + +- ``date`` - Print or set current date and time + +- ``echo`` - Produce message in a shell script + +- ``sleep`` - Delay for a specified amount of time + +- ``id`` - show uid gid euid and egid + +- ``tty`` - show ttyname + +- ``whoami`` - print effective user id + +- ``getenv`` - print environment variable + +- ``setenv`` - set environment variable + +- ``unsetenv`` - unset environment variable + +- ``time`` - time command execution + +- ``logoff`` - logoff from the system + +- ``rtc`` - RTC driver configuration + +- ``exit`` - alias for logoff command + +Commands +======== + +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. + +help - Print command help +------------------------- +.. index:: help + +**SYNOPSYS:** + +.. code:: c + + 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. + +alias - add alias for an existing command +----------------------------------------- +.. index:: alias + +**SYNOPSYS:** + +.. code:: c + + alias oldCommand newCommand + +**DESCRIPTION:** + +This command adds an alternate name for an existing command to the command set. + +**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 ``alias``: +.. code:: c + + SHLL \[/] $ me + shell:me command not found + SHLL \[/] $ alias whoami me + SHLL \[/] $ me + rtems + SHLL \[/] $ whoami + rtems + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_alias + +The ``alias`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_alias( + int argc, + char \**argv + ); + +The configuration structure for the ``alias`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ALIAS_Command; + +cmdls - List commands +--------------------- +.. index:: cmdls + +**SYNOPSYS:** + +.. code:: c + + cmdls COMMAND... + +**DESCRIPTION:** + +This command lists the visible commands of the command set. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +The current user must have read permission to list a command. + +**EXAMPLES:** + +The following is an example of how to use ``cmdls``: +.. code:: c + + SHLL \[/] # cmdls help shutdown + r-xr-xr-x 0 0 help + r-x------ 0 0 shutdown + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDLS_Command; + +cmdchown - Change user or owner of commands +------------------------------------------- +.. index:: cmdchown + +**SYNOPSYS:** + +.. code:: c + + cmdchown \[OWNER][:\[GROUP]] COMMAND... + +**DESCRIPTION:** + +This command changes the user or owner of a command. + +**EXIT STATUS:** + +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 +owner or group. + +**EXAMPLES:** + +The following is an example of how to use ``cmdchown``: +.. code:: c + + [/] # cmdls help + r-xr-xr-x 0 0 help + \[/] # cmdchown 1:1 help + \[/] # cmdls help + r--r--r-- 1 1 help + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command; + +cmdchmod - Change mode of commands +---------------------------------- +.. index:: cmdchmod + +**SYNOPSYS:** + +.. code:: c + + cmdchmod OCTAL-MODE COMMAND... + +**DESCRIPTION:** + +This command changes the mode of a command. + +**EXIT STATUS:** + +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. + +**EXAMPLES:** + +The following is an example of how to use ``cmdchmod``: +.. code:: c + + [/] # cmdls help + r-xr-xr-x 0 0 help + \[/] # cmdchmod 544 help + \[/] # cmdls help + r-xr--r-- 0 0 help + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command; + +date - print or set current date and time +----------------------------------------- +.. index:: date + +**SYNOPSYS:** + +.. code:: c + + 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. + +The ``date`` is specified in ``YYYY-MM-DD`` format. +The ``time`` is specified in ``HH:MM:SS`` format. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This comm + +**EXAMPLES:** + +The following is an example of how to use ``date``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_date + +The ``date`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_date( + int argc, + char \**argv + ); + +The configuration structure for the ``date`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DATE_Command; + +echo - produce message in a shell script +---------------------------------------- +.. index:: echo + +**SYNOPSYS:** + +.. code:: c + + 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. + +If any of the following sequences of characters is encountered during +output, the sequence is not output. Instead, the specified action is +performed: + +*\\b* + A backspace character is output. + +*\\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. + +*\\f* + Output a form feed. + +*\\n* + Output a newline character. + +*\\r* + Output a carriage return. + +*\\t* + Output a (horizontal) tab character. + +*\\v* + Output a vertical tab. + +*\\0digits* + Output the character whose value is given by zero to three digits. + If there are zero digits, a nul character is output. + +*\\\\* + Output a backslash. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +The octal character escape mechanism (\\0digits) differs from the C lan- +guage mechanism. + +There is no way to force ``echo`` to treat its arguments literally, rather +than interpreting them as options and escape sequences. + +**EXAMPLES:** + +The following is an example of how to use ``echo``: +.. code:: c + + SHLL \[/] $ echo a b c + a b c + SHLL \[/] $ echo + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_echo + +The ``echo`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_echo( + int argc, + char \**argv + ); + +The configuration structure for the ``echo`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ECHO_Command; + +**ORIGIN:** + +The implementation and portions of the documentation for this +command are from NetBSD 4.0. + +sleep - delay for a specified amount of time +-------------------------------------------- +.. index:: sleep + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This command is implemented using the ``nanosleep()`` method. + +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``. + +**EXAMPLES:** + +The following is an example of how to use ``sleep``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_sleep + +The ``sleep`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_sleep( + int argc, + char \**argv + ); + +The configuration structure for the ``sleep`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SLEEP_Command; + +id - show uid gid euid and egid +------------------------------- +.. index:: id + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**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. + +**EXAMPLES:** + +The first example of the ``id`` command is from a session logged +in as the normal user ``rtems``: +.. code:: c + + 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: +.. code:: c + + SHLL \[/] # id + uid=0(root),gid=0(root),euid=0(root),egid=0(root) + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_id + +The ``id`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_id( + int argc, + char \**argv + ); + +The configuration structure for the ``id`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ID_Command; + +tty - show ttyname +------------------ +.. index:: tty + +**SYNOPSYS:** + +.. code:: c + + tty + +**DESCRIPTION:** + +This command prints the file name of the device connected +to standard input. + +**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 ``tty``: +.. code:: c + + SHLL \[/] $ tty + /dev/console + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_tty + +The ``tty`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_tty( + int argc, + char \**argv + ); + +The configuration structure for the ``tty`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TTY_Command; + +whoami - print effective user id +-------------------------------- +.. index:: whoami + +**SYNOPSYS:** + +.. code:: c + + whoami + +**DESCRIPTION:** + +This command displays the user name associated with the current +effective user id. + +**EXIT STATUS:** + +This command always succeeds. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``whoami``: +.. code:: c + + SHLL \[/] $ whoami + rtems + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_whoami + +The ``whoami`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_whoami( + int argc, + char \**argv + ); + +The configuration structure for the ``whoami`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command; + +getenv - print environment variable +----------------------------------- +.. index:: getenv + +**SYNOPSYS:** + +.. code:: c + + getenv variable + +**DESCRIPTION:** + +This command is used to display the value of a ``variable`` in the set +of environment variables. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``getenv``: +.. code:: c + + SHLL \[/] $ getenv BASEPATH + /mnt/hda1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_getenv + +The ``getenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_getenv( + int argc, + char \**argv + ); + +The configuration structure for the ``getenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_GETENV_Command; + +setenv - set environment variable +--------------------------------- +.. index:: setenv + +**SYNOPSYS:** + +.. code:: c + + 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. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``setenv``: +.. code:: c + + SHLL \[/] $ setenv BASEPATH /mnt/hda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_setenv + +The ``setenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_setenv( + int argc, + char \**argv + ); + +The configuration structure for the ``setenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SETENV_Command; + +unsetenv - unset environment variable +------------------------------------- +.. index:: unsetenv + +**SYNOPSYS:** + +.. code:: c + + unsetenv variable + +**DESCRIPTION:** + +This command is remove to a ``variable`` from the set of environment +variables. + +**EXIT STATUS:** + +This command will return 1 and print a diagnostic message if +a failure occurs. + +**NOTES:** + +The entire RTEMS application shares a single set of environment variables. + +**EXAMPLES:** + +The following is an example of how to use ``unsetenv``: +.. code:: c + + SHLL \[/] $ unsetenv BASEPATH + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_unsetenv + +The ``unsetenv`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_unsetenv( + int argc, + char \**argv + ); + +The configuration structure for the ``unsetenv`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command; + +time - time command execution +----------------------------- +.. index:: time + +**SYNOPSYS:** + +.. code:: c + + time command \[argument ...] + +**DESCRIPTION:** + +The time command executes and times a command. After the command +finishes, time writes the total time elapsed. Times are reported in +seconds. + +**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 ``time``: +.. code:: c + + SHLL \[/] $ time cp -r /nfs/directory /c + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_time + +The ``time`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_time( + int argc, + char \**argv + ); + +The configuration structure for the ``time`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TIME_Command; + +logoff - logoff from the system +------------------------------- +.. index:: logoff + +**SYNOPSYS:** + +.. code:: c + + logoff + +**DESCRIPTION:** + +This command logs the user out of the shell. + +**EXIT STATUS:** + +This command does not return. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``logoff``: +.. code:: c + + SHLL \[/] $ logoff + logoff from the system... + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_logoff + +The ``logoff`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_logoff( + int argc, + char \**argv + ); + +The configuration structure for the ``logoff`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command; + +rtc - RTC driver configuration +------------------------------ +.. index:: rtc + +**SYNOPSYS:** + +.. code:: c + + rtc + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all +shell commands have been configured. + +exit - exit the shell +--------------------- +.. index:: exit + +**SYNOPSYS:** + +.. code:: c + + exit + +**DESCRIPTION:** + +This command causes the shell interpreter to ``exit``. + +**EXIT STATUS:** + +This command does not return. + +**NOTES:** + +In contrast to `logoff - logoff from the system`_, +this command is built into the shell interpreter loop. + +**EXAMPLES:** + +The following is an example of how to use ``exit``: +.. code:: c + + SHLL \[/] $ exit + Shell exiting + +**CONFIGURATION:** + +This command is always present and cannot be disabled. + +**PROGRAMMING INFORMATION:** + +The ``exit`` is implemented directly in the shell interpreter. +There is no C routine associated with it. + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +File and Directory Commands +########################### + +Introduction +============ + +The RTEMS shell has the following file and directory commands: + +- ``blksync`` - sync the block driver + +- ``cat`` - display file contents + +- ``cd`` - alias for chdir + +- ``chdir`` - change the current directory + +- ``chmod`` - change permissions of a file + +- ``chroot`` - change the root directory + +- ``cp`` - copy files + +- ``dd`` - format disks + +- ``debugrfs`` - debug RFS file system + +- ``df`` - display file system disk space usage + +- ``dir`` - alias for ls + +- ``fdisk`` - format disks + +- ``hexdump`` - format disks + +- ``ln`` - make links + +- ``ls`` - list files in the directory + +- ``md5`` - display file system disk space usage + +- ``mkdir`` - create a directory + +- ``mkdos`` - DOSFS disk format + +- ``mknod`` - make device special file + +- ``mkrfs`` - format RFS file system + +- ``mount`` - mount disk + +- ``mv`` - move files + +- ``pwd`` - print work directory + +- ``rmdir`` - remove empty directories + +- ``rm`` - remove files + +- ``umask`` - Set file mode creation mask + +- ``unmount`` - unmount disk + +Commands +======== + +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. + +blksync - sync the block driver +------------------------------- +.. index:: blksync + +**SYNOPSYS:** + +.. code:: c + + blksync driver + +**DESCRIPTION:** + +This command XXX + +**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 ``blksync``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_blksync + +The ``blksync`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_blksync( + int argc, + char \**argv + ); + +The configuration structure for the ``blksync`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command; + +cat - display file contents +--------------------------- +.. index:: cat + +**SYNOPSYS:** + +.. code:: c + + cat file1 \[file2 .. fileN] + +**DESCRIPTION:** + +This command displays the contents of the specified files. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +It is possible to read the input from a device file using ``cat``. + +**EXAMPLES:** + +The following is an example of how to use ``cat``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_cat + +The ``cat`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cat( + int argc, + char \**argv + ); + +The configuration structure for the ``cat`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CAT_Command; + +cd - alias for chdir +-------------------- +.. index:: cd + +**SYNOPSYS:** + +.. code:: c + + cd directory + +**DESCRIPTION:** + +This command is an alias or alternate name for the ``chdir``. +See `ls - list files in the directory`_ for more information. + +**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 ``cd``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_cd + +The ``cd`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cd( + int argc, + char \**argv + ); + +The configuration structure for the ``cd`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CD_Command; + + +chdir - change the current directory +------------------------------------ +.. index:: chdir + +**SYNOPSYS:** + +.. code:: c + + 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 ``/``. + +**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 ``chdir``: +.. code:: c + + SHLL \[/] $ pwd + / + SHLL \[/] $ chdir etc + SHLL \[/etc] $ pwd + /etc + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_chdir + +The ``chdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chdir( + int argc, + char \**argv + ); + +The configuration structure for the ``chdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHDIR_Command; + +chmod - change permissions of a file +------------------------------------ +.. index:: chmod + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_chmod + +The ``chmod`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chmod( + int argc, + char \**argv + ); + +The configuration structure for the ``chmod`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHMOD_Command; + +chroot - change the root directory +---------------------------------- +.. index:: chroot + +**SYNOPSYS:** + +.. code:: c + + chroot \[dir] + +**DESCRIPTION:** + +This command changes the root directory to ``dir`` for subsequent +commands. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +The destination directory ``dir`` must exist. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``chroot`` +and the impact it has on the environment for subsequent +command invocations: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_chroot + +The ``chroot`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_chroot( + int argc, + char \**argv + ); + +The configuration structure for the ``chroot`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CHROOT_Command; + +cp - copy files +--------------- +.. index:: cp + +**SYNOPSYS:** + +.. code:: c + + cp \[-R \[-H | -L | -P]] \[-f | -i] \[-pv] src target + cp \[-R \[-H | -L] ] \[-f | -i] \[-NpPv] source_file ... target_directory + +**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. + +The following options are available: + +*-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:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_main_cp + +The ``cp`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_main_cp( + int argc, + char \**argv + ); + +The configuration structure for the ``cp`` has the +following prototype: +.. code:: c + + 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. + +dd - convert and copy a file +---------------------------- +.. index:: dd + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + SHLL \[/] $ dd if=/nfs/boot-image of=/dev/hda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_dd + +The ``dd`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dd( + int argc, + char \**argv + ); + +The configuration structure for the ``dd`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DD_Command; + +debugrfs - debug RFS file system +-------------------------------- +.. index:: debugrfs + +**SYNOPSYS:** + +.. code:: c + + debugrfs \[-hl] path command \[options] + +**DESCRIPTION:** + +The command provides debugging information for the RFS file system. + +The options are: + +*-h* + Print a help message. + +*-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. + +The commands are: + +*block start \[end]* + Display the contents of the blocks from start to end. + +*data* + Display the file system data and configuration. + +*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. + +*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. + + *-e* + + Search and display on inodes that have an error. + + *-f* + + Force display of inodes, even when in error. + +**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 ``debugrfs``: +.. code:: c + + SHLL \[/] $ debugrfs /c data + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_debugrfs + +The ``debugrfs`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_debugrfs( + int argc, + char \**argv + ); + +The configuration structure for ``debugrfs`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command; + +df - display file system disk space usage +----------------------------------------- +.. index:: df + +**SYNOPSYS:** + +.. code:: c + + df \[-h] \[-B block_size] + +**DESCRIPTION:** + +This command print disk space usage for mounted file systems. + +**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 ``df``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_df + +The ``df`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_df( + int argc, + char \**argv + ); + +The configuration structure for the ``df`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DF_Command; + +dir - alias for ls +------------------ +.. index:: dir + +**SYNOPSYS:** + +.. code:: c + + dir \[dir] + +**DESCRIPTION:** + +This command is an alias or alternate name for the ``ls``. +See `ls - list files in the directory`_ +for more information. + +**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 ``dir``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_dir + +The ``dir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dir( + int argc, + char \**argv + ); + +The configuration structure for the ``dir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DIR_Command; + +fdisk - format disk +------------------- +.. index:: fdisk + +**SYNOPSYS:** + +.. code:: c + + fdisk + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all +shell commands have been configured. + +hexdump - ascii/dec/hex/octal dump +---------------------------------- +.. index:: hexdump + +**SYNOPSYS:** + +.. code:: c + + 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. + +*-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. + +*-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:: c + + SHLL \[/] $ hexdump -C -n 512 /dev/hda1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_hexdump + +The ``hexdump`` command is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_hexdump( + int argc, + char \**argv + ); + +The configuration structure for the ``hexdump`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command; + +ln - make links +--------------- +.. index:: ln + +**SYNOPSYS:** + +.. code:: 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: + +*-f* + Unlink any already existing file, permitting the link to occur. + +*-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. + +*-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.) + +*-n* + Same as -h, for compatibility with other ln implementations. + +*-s* + Create a symbolic link. + +*-v* + Cause ln to be verbose, showing files as they are processed. + +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. + +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. + +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. + +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. + +**EXIT STATUS:** + +The ``ln`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] ln -s /dev/console /dev/con1 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ln + +The ``ln`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ln( + int argc, + char \**argv + ); + +The configuration structure for the ``ln`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LN_Command; + +**ORIGIN:** + +The implementation and portions of the documentation for this command +are from NetBSD 4.0. + +ls - list files in the directory +-------------------------------- +.. index:: ls + +**SYNOPSYS:** + +.. code:: c + + 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:** + +This command returns 0 on success and non-zero if an error is encountered. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``ls``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ls + +The ``ls`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ls( + int argc, + char \**argv + ); + +The configuration structure for the ``ls`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LS_Command; + +md5 - compute the Md5 hash of a file or list of files +----------------------------------------------------- +.. index:: md5 + +**SYNOPSYS:** + +.. code:: c + + 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``md5``: +.. code:: c + + SHLL \[/] $ md5 shell-init + MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_md5 + +The ``df`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_md5( + int argc, + char \**argv + ); + +The configuration structure for the ``md5`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MD5_Command; + +mkdir - create a directory +-------------------------- +.. index:: mkdir + +**SYNOPSYS:** + +.. code:: 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. + +**NOTES:** + +If this command is invoked with no arguments, nothing occurs. + +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``. + +**EXAMPLES:** + +The following is an example of how to use ``mkdir``: +.. code:: c + + 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 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_mkdir + +The ``mkdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkdir( + int argc, + char \**argv + ); + +The configuration structure for the ``mkdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKDIR_Command; + +mldos - DOSFS file system format +-------------------------------- +.. index:: pwd + +**SYNOPSYS:** + +.. code:: c + + mkdir \[-V label] \[-s sectors/cluster] \[-r size] \[-v] path + +**DESCRIPTION:** + +This command formats a block device entry with the DOSFS file system. + +*-V label* + +*-s sectors/cluster* + +*-r 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 ``mkdos``: +.. code:: c + + SHLL \[/] $ mkdos /dev/rda1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_mkdos + +The ``mkdos`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkdos( + int argc, + char \**argv + ); + +The configuration structure for the ``mkdos`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKDOS_Command; + +mknod - make device special file +-------------------------------- +.. index:: mknod + +**SYNOPSYS:** + +.. code:: c + + 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. + +*-R* + Replace an existing file if its type is incorrect. Correct the + mode, user and group. + +*-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. + +*-m mode* + Specify the mode for the device node. The mode may be absolute or + symbolic, see *chmod*. + +*-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. + +*name* + Device name, for example “tty” for a termios serial device or “hd” + for a disk. + +*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. + +*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. + +*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. + +*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). + +*number* + A single opaque device number. Useful for netbooted computers which + require device numbers packed in a format that isn’t supported by + -F. + +**EXIT STATUS:** + +The ``mknod`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] mknod c 3 0 /dev/ttyS10 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mknod + +The ``mknod`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mknod( + int argc, + char \**argv + ); + +The configuration structure for the ``mknod`` has the following +prototype: +.. code:: c + + 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. + +mkrfs - format RFS file system +------------------------------ +.. index:: mkrfs + +**SYNOPSYS:** + +.. code:: c + + mkrfs \[-vsbiIo] device + +**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 following options are provided: + +*-v* + Display configuration and progress of the format. + +*-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. + +*-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. + +*-o* + Integer percentage of the media used by inodes. The default is 1%. + +*device* + Path of the device to format. + +**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 ``mkrfs``: +.. code:: c + + SHLL \[/] $ mkrfs /dev/fdda + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mkrfs + +The ``mkrfs`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mkrfs( + int argc, + char \**argv + ); + +The configuration structure for ``mkrfs`` has the following +prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MKRFS_Command; + +mount - mount disk +------------------ +.. index:: mount + +**SYNOPSYS:** + +.. code:: c + + mount \[-t fstype] \[-r] \[-L] device path + +**DESCRIPTION:** + +The ``mount`` command will mount a block device to a mount point +using the specified file system. The files systems are: + +- msdos - MSDOS File System + +- tftp - TFTP Network File System + +- ftp - FTP Network File System + +- nfs - Network File System + +- rfs - RTEMS 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. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +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. + +**EXAMPLES:** + +Mount the Flash Disk driver to the ’/fd’ mount point: +.. code:: c + + SHLL \[/] $ mount -t msdos /dev/flashdisk0 /fd + +Mount the NFS file system exported path ’bar’ by host ’foo’: +.. code:: c + + $ mount -t nfs foo:/bar /nfs + +Mount the TFTP file system on ’/tftp’: +.. code:: c + + $ mount -t tftp /tftp + +To access the TFTP files on server ’10.10.10.10’: +.. code:: c + + $ cat /tftp/10.10.10.10/test.txt + +**CONFIGURATION:** + +.. 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. + +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: + +- msdos - CONFIGURE_SHELL_MOUNT_MSDOS + +- tftp - CONFIGURE_SHELL_MOUNT_TFTP + +- ftp - CONFIGURE_SHELL_MOUNT_FTP + +- nfs - CONFIGURE_SHELL_MOUNT_NFS + +- rfs - CONFIGURE_SHELL_MOUNT_RFS + +An example configuration is: +.. code:: c + + #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 + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mount + +The ``mount`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mount( + int argc, + char \**argv + ); + +The configuration structure for the ``mount`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MOUNT_Command; + +mv - move files +--------------- +.. index:: mv + +**SYNOPSYS:** + +.. code:: c + + mv \[-fiv] source_file target_file + mv \[-fiv] source_file... target_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. + +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. + +The following options are available: + +*-f* + Do not prompt for confirmation before overwriting the destination + path. + +*-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. + +It is an error for the source operand to specify a directory if the +target exists and is not a directory. + +If the destination path does not have a mode which permits writing, mv +prompts the user for confirmation as specified for the -i option. + +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: +.. code:: c + + rm -f destination_path && \\ + cp -PRp source_file destination_path && \\ + rm -rf source_file + +**EXIT STATUS:** + +The ``mv`` utility exits 0 on success, and >0 if an error occurs. + +**NOTES:** + +NONE + +**EXAMPLES:** + +.. code:: c + + SHLL \[/] mv /dev/console /dev/con1 + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_main_mv + +The ``mv`` command is implemented by a C language function which +has the following prototype: +.. code:: c + + int rtems_shell_main_mv( + int argc, + char \**argv + ); + +The configuration structure for the ``mv`` has the +following prototype: +.. code:: c + + 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. + +pwd - print work directory +-------------------------- +.. index:: pwd + +**SYNOPSYS:** + +.. code:: c + + pwd + +**DESCRIPTION:** + +This command prints the fully qualified filename of the current +working directory. + +**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 ``pwd``: +.. code:: c + + SHLL \[/] $ pwd + / + SHLL \[/] $ cd dev + SHLL \[/dev] $ pwd + /dev + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_pwd + +The ``pwd`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_pwd( + int argc, + char \**argv + ); + +The configuration structure for the ``pwd`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PWD_Command; + +rmdir - remove empty directories +-------------------------------- +.. index:: rmdir + +**SYNOPSYS:** + +.. code:: c + + rmdir \[dir1 .. dirN] + +**DESCRIPTION:** + +This command removes the specified set of directories. If no +directories are provided on the command line, no actions are taken. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +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``: +.. code:: c + + SHLL \[/] # mkdir joeldir + SHLL \[/] # rmdir joeldir + SHLL \[/] # ls joeldir + joeldir: No such file or directory. + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_rmdir + +The ``rmdir`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_rmdir( + int argc, + char \**argv + ); + +The configuration structure for the ``rmdir`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_RMDIR_Command; + +rm - remove files +----------------- +.. index:: rm + +**SYNOPSYS:** + +.. code:: c + + rm file1 \[file2 ... fileN] + +**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. + +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. + +**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 ``rm``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_main_rm + +The ``rm`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_main_rm( + int argc, + char \**argv + ); + +The configuration structure for the ``rm`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_RM_Command; + +umask - set file mode creation mask +----------------------------------- +.. index:: umask + +**SYNOPSYS:** + +.. code:: c + + umask \[new_umask] + +**DESCRIPTION:** + +This command sets the user file creation mask to ``new_umask``. The +argument ``new_umask`` may be octal, hexadecimal, or decimal. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +This command does not currently support symbolic mode masks. + +**EXAMPLES:** + +The following is an example of how to use ``umask``: +.. code:: c + + SHLL \[/] $ umask + 022 + SHLL \[/] $ umask 0666 + 0666 + SHLL \[/] $ umask + 0666 + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_umask + +The ``umask`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_umask( + int argc, + char \**argv + ); + +The configuration structure for the ``umask`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UMASK_Command; + +unmount - unmount disk +---------------------- +.. index:: unmount + +**SYNOPSYS:** + +.. code:: c + + unmount path + +**DESCRIPTION:** + +This command unmounts the device at the specified ``path``. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +TBD - Surely there must be some warnings to go here. + +**EXAMPLES:** + +The following is an example of how to use ``unmount``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_unmount + +The ``unmount`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_unmount( + int argc, + char \**argv + ); + +The configuration structure for the ``unmount`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command; + +.. COMMENT: COPYRIGHT (c) 1988-2012. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +Memory Commands +############### + +Introduction +============ + +The RTEMS shell has the following memory commands: + +- ``mdump`` - Display contents of memory + +- ``wdump`` - Display contents of memory (word) + +- ``ldump`` - Display contents of memory (longword) + +- ``medit`` - Modify contents of memory + +- ``mfill`` - File memory with pattern + +- ``mmove`` - Move contents of memory + +- ``malloc`` - Obtain information on C Program Heap + +Commands +======== + +This section details the Memory 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. + +mdump - display contents of memory +---------------------------------- +.. index:: mdump + +**SYNOPSYS:** + +.. code:: c + + 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. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``mdump``: +.. code:: c + + 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 ..`....... ..(.. + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mdump + +The ``mdump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mdump( + int argc, + char \**argv + ); + +The configuration structure for the ``mdump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MDUMP_Command; + +wdump - display contents of memory (word) +----------------------------------------- +.. index:: wdump + +**SYNOPSYS:** + +.. code:: c + + 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``. + +When ``length`` is not provided, it defaults to ``320`` which +is twenty lines of output with eight words of output per line. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``wdump``: +.. code:: c + + SHLL \[/] $ wdump 0x02010000 32 + 0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t + 0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ............... + +**CONFIGURATION:** + +.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP +.. index:: CONFIGURE_SHELL_COMMAND_WDUMP + +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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_wdump + +The ``wdump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_wdump( + int argc, + char \**argv + ); + +The configuration structure for the ``wdump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WDUMP_Command; + +ldump - display contents of memory (longword) +--------------------------------------------- +.. index:: ldump + +**SYNOPSYS:** + +.. code:: c + + ldump \[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 4``. + +When ``length`` is not provided, it defaults to ``320`` which +is twenty lines of output with four longwords of output per line. + +When ``address`` is not provided, it defaults to ``0x00000000``. + +**EXIT STATUS:** + +This command always returns 0 to indicate success. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``ldump``: +.. code:: c + + SHLL \[/] $ ldump 0x02010000 32 + 0x02010000 020108D8 020108C0-020108AC 02010874 ...............t + 0x02010010 020 0894 02010718-02010640 02010798 ............... + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ldump + +The ``ldump`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ldump( + int argc, + char \**argv + ); + +The configuration structure for the ``ldump`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_LDUMP_Command; + +medit - modify contents of memory +--------------------------------- +.. index:: medit + +**SYNOPSYS:** + +.. code:: c + + medit address value1 \[value2 ... valueN] + +**DESCRIPTION:** + +This command is used to modify the contents of the memory starting +at ``address`` using the octets specified by the parameters``value1`` through ``valueN``. + +**EXIT STATUS:** + +This command returns 0 on success and non-zero if an error is encountered. + +**NOTES:** + +Dumping memory from a non-existent address may result in an unrecoverable +program fault. + +**EXAMPLES:** + +The following is an example of how to use ``medit``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_medit + +The ``medit`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_medit( + int argc, + char \**argv + ); + +The configuration structure for the ``medit`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MEDIT_Command; + +mfill - file memory with pattern +-------------------------------- +.. index:: mfill + +**SYNOPSYS:** + +.. code:: c + + mfill address length 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:** + +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. + +**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:: c + + 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:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mfill + +The ``mfill`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mfill( + int argc, + char \**argv + ); + +The configuration structure for the ``mfill`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MFILL_Command; + +mmove - move contents of memory +------------------------------- +.. index:: mmove + +**SYNOPSYS:** + +.. code:: c + + mmove dst src length + +**DESCRIPTION:** + +This command is used to copy the contents of the memory +starting at ``src`` to the memory located at ``dst`` +for the specified ``length`` in octets. + +**EXIT STATUS:** + +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 ``mmove``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_mmove + +The ``mmove`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_mmove( + int argc, + char \**argv + ); + +The configuration structure for the ``mmove`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MMOVE_Command; + +malloc - obtain information on C program heap +--------------------------------------------- +.. index:: malloc + +**SYNOPSYS:** + +.. code:: c + + 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: + +- Number of free blocks + +- Largest free block + +- Total bytes free + +- Number of used blocks + +- Largest used block + +- Total bytes used + +- Size of the allocatable area in bytes + +- Minimum free size ever in bytes + +- Maximum number of free blocks ever + +- Maximum number of blocks searched ever + +- Lifetime number of bytes allocated + +- Lifetime number of bytes freed + +- Total number of searches + +- Total number of successful allocations + +- Total number of failed allocations + +- Total number of successful frees + +- Total number of successful resizes + +When the subcommand ``walk`` is specified, then a heap walk will be +performed and information about each block is printed out. + +**EXIT STATUS:** + +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 the ``malloc`` command. +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_malloc + +The ``malloc`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_malloc( + int argc, + char \**argv + ); + +The configuration structure for the ``malloc`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_MALLOC_Command; + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +RTEMS Specific Commands +####################### + +Introduction +============ + +The RTEMS shell has the following rtems commands: + +- ``shutdown`` - Shutdown the system + +- ``cpuuse`` - print or reset per thread cpu usage + +- ``stackuse`` - print per thread stack usage + +- ``perioduse`` - print or reset per period usage + +- ``profreport`` - print a profiling report + +- ``wkspace`` - Display information on Executive Workspace + +- ``config`` - Show the system configuration. + +- ``itask`` - List init tasks for the system + +- ``extension`` - Display information about extensions + +- ``task`` - Display information about tasks + +- ``queue`` - Display information about message queues + +- ``sema`` - display information about semaphores + +- ``region`` - display information about regions + +- ``part`` - display information about partitions + +- ``object`` - Display information about RTEMS objects + +- ``driver`` - Display the RTEMS device driver table + +- ``dname`` - Displays information about named drivers + +- ``pthread`` - Displays information about POSIX threads + +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. + +shutdown - Shutdown the system +------------------------------ +.. index:: shutdown + +**SYNOPSYS:** + +.. code:: c + + shutdown + +**DESCRIPTION:** + +This command is used to shutdown the RTEMS application. + +**EXIT STATUS:** + +This command does not return. + +**NOTES:** + +**EXAMPLES:** + +The following is an example of how to use ``shutdown``: +.. code:: c + + SHLL \[/] $ shutdown + System shutting down at user request + +The user will not see another prompt and the system will +shutdown. + +**CONFIGURATION:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command; + +cpuuse - print or reset per thread cpu usage +-------------------------------------------- +.. index:: cpuuse + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_cpuuse + +The ``cpuuse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_cpuuse( + int argc, + char \**argv + ); + +The configuration structure for the ``cpuuse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command; + +stackuse - print per thread stack usage +--------------------------------------- +.. index:: stackuse + +**SYNOPSYS:** + +.. code:: c + + stackuse + +**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:** + +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. + +**EXAMPLES:** + +The following is an example of how to use ``stackuse``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_stackuse + +The ``stackuse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_stackuse( + int argc, + char \**argv + ); + +The configuration structure for the ``stackuse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command; + +perioduse - print or reset per period usage +------------------------------------------- +.. index:: perioduse + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_perioduse + +The ``perioduse`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_perioduse( + int argc, + char \**argv + ); + +The configuration structure for the ``perioduse`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command; + +profreport - print a profiling report +------------------------------------- +.. index:: profreport + +**SYNOPSYS:** + +.. code:: c + + profreport + +**DESCRIPTION:** + +This command may be used to print a profiling report. + +**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:: c + + 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:** + +.. 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. + +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: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command; + +wkspace - display information on executive workspace +---------------------------------------------------- +.. index:: wkspace + +**SYNOPSYS:** + +.. code:: c + + wkspace + +**DESCRIPTION:** + +This command prints information on the current state of +the RTEMS Executive Workspace reported. This includes the +following information: + +- Number of free blocks + +- Largest free block + +- Total bytes free + +- Number of used blocks + +- Largest used block + +- Total bytes used + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``wkspace``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_wkspace + +The ``wkspace`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_wkspace( + int argc, + char \**argv + ); + +The configuration structure for the ``wkspace`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command; + +config - show the system configuration. +--------------------------------------- +.. index:: config + +**SYNOPSYS:** + +.. code:: c + + config + +**DESCRIPTION:** + +This command display information about the RTEMS Configuration. + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**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. + +**EXAMPLES:** + +The following is an example of how to use ``config``: +.. code:: c + + 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:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_config + +The ``config`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_config( + int argc, + char \**argv + ); + +The configuration structure for the ``config`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_CONFIG_Command; + +itask - list init tasks for the system +-------------------------------------- +.. index:: itask + +**SYNOPSYS:** + +.. code:: c + + itask + +**DESCRIPTION:** + +This command prints a report on the set of initialization +tasks and threads in the system. + +**EXIT STATUS:** + +This command always succeeds and returns 0. + +**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:** + +The following is an example of how to use ``itask``: +.. code:: c + + SHLL \[/] $ itask + # NAME ENTRY ARGUMENT PRIO MODES ATTRIBUTES STACK SIZE + ------------------------------------------------------------------------------ + 0 UI1 \[0x2002258] 0 \[0x0] 1 nP DEFAULT 4096 \[0x1000] + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_itask + +The ``itask`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_itask( + int argc, + char \**argv + ); + +The configuration structure for the ``itask`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ITASK_Command; + +extension - display information about extensions +------------------------------------------------ +.. index:: extension + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 using the ``extension`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ extension + ID NAME + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_extension + +The ``extension`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_extension( + int argc, + char \**argv + ); + +The configuration structure for the ``extension`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command; + +task - display information about tasks +-------------------------------------- +.. index:: task + +**SYNOPSYS:** + +.. code:: c + + task \[id \[id ...] ] + +**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. + +**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 the ``task`` on an +application with just two Classic API tasks: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_task + +The ``task`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_task( + int argc, + char \**argv + ); + +The configuration structure for the ``task`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_TASK_Command; + +queue - display information about message queues +------------------------------------------------ +.. index:: queue + +**SYNOPSYS:** + +.. code:: c + + queue \[id \[id ... ] ] + +**DESCRIPTION:** + +When invoked with no arguments, this command prints information on +the set of Classic API Message Queues 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of using the ``queue`` command +on a system with no Classic API Message Queues. +.. code:: c + + SHLL \[/] $ queue + ID NAME ATTRIBUTES PEND MAXPEND MAXSIZE + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_queue + +The ``queue`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_queue( + int argc, + char \**argv + ); + +The configuration structure for the ``queue`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_QUEUE_Command; + +sema - display information about semaphores +------------------------------------------- +.. index:: sema + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``sema``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_sema + +The ``sema`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_sema( + int argc, + char \**argv + ); + +The configuration structure for the ``sema`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_SEMA_Command; + +region - display information about regions +------------------------------------------ +.. index:: region + +**SYNOPSYS:** + +.. code:: c + + region \[id \[id ... ] ] + +**DESCRIPTION:** + +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. + +**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 using the ``region`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ region + ID NAME ATTR STARTADDR LENGTH PAGE_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_region + +The ``region`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_region( + int argc, + char \**argv + ); + +The configuration structure for the ``region`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_REGION_Command; + +part - display information about partitions +------------------------------------------- +.. index:: part + +**SYNOPSYS:** + +.. code:: c + + part \[id \[id ... ] ] + +**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. + +**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 using the ``part`` command +on a system with no user extensions. +.. code:: c + + SHLL \[/] $ part + ID NAME ATTR STARTADDR LENGTH BUF_SIZE USED_BLOCKS + ------------------------------------------------------------------------------ + +**CONFIGURATION:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_part + +The ``part`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_part( + int argc, + char \**argv + ); + +The configuration structure for the ``part`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PART_Command; + +object - display information about rtems objects +------------------------------------------------ +.. index:: object + +**SYNOPSYS:** + +.. code:: c + + object \[id \[id ...] ] + +**DESCRIPTION:** + +When invoked with a set of object ids as arguments, then +a report on those objects is printed. + +**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 ``object``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_object + +The ``object`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_object( + int argc, + char \**argv + ); + +The configuration structure for the ``object`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_OBJECT_Command; + +driver - display the rtems device driver table +---------------------------------------------- +.. index:: driver + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``driver``: +.. code:: c + + 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_driver + +The ``driver`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_driver( + int argc, + char \**argv + ); + +The configuration structure for the ``driver`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DRIVER_Command; + +dname - displays information about named drivers +------------------------------------------------ +.. index:: dname + +**SYNOPSYS:** + +.. code:: c + + dname + +**DESCRIPTION:** + +This command XXX + +WARNING! XXX 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. + +**NOTES:** + +NONE + +**EXAMPLES:** + +The following is an example of how to use ``dname``: +.. code:: c + + EXAMPLE_TBD + +**CONFIGURATION:** + +.. 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. + +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:** + +.. index:: rtems_shell_rtems_main_dname + +The ``dname`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_dname( + int argc, + char \**argv + ); + +The configuration structure for the ``dname`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_DNAME_Command; + +pthread - display information about POSIX threads +------------------------------------------------- +.. index:: pthread + +**SYNOPSYS:** + +.. code:: c + + 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. + +**NOTES:** + +This command is only available when the POSIX API is configured. + +**EXAMPLES:** + +The following is an example of how to use the ``task`` on an +application with four POSIX threads: +.. code:: c + + 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 + +**CONFIGURATION:** + +This command is part of the monitor commands which are always +available in the shell. + +**PROGRAMMING INFORMATION:** + +This command is not directly available for invocation. + +.. COMMENT: COPYRIGHT (c) 1988-2008. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + +Network Commands +################ + +Introduction +============ + +The RTEMS shell has the following network commands: + +- ``netstats`` - obtain network statistics + +- ``ifconfig`` - configure a network interface + +- ``route`` - show or manipulate the IP routing table + +- ``ping`` - ping a host or IP address + +Commands +======== + +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. + +netstats - obtain network statistics +------------------------------------ +.. index:: netstats + +**SYNOPSYS:** + +.. code:: c + + 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 + +*-u* + print UDP Statistics + +*-t* + print TCP Statistics + +**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 ``netstats``: + +The following is an example of using the ``netstats`` +command to print the IP routing table: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the MBUF statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the print the interface statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the print IP statistics: +.. code:: c + + [/] $ 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 + +The following is an example of using the ``netstats`` +command to print the ICMP statistics: +.. code:: c + + [/] $ 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:: c + + [/] $ netstats -u + \************ UDP Statistics \************ + +The following is an example of using the ``netstats`` +command to print the TCP statistics: +.. code:: c + + [/] $ 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:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_netstats + +The ``netstats`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_netstats( + int argc, + char \**argv + ); + +The configuration structure for the ``netstats`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command; + +ifconfig - configure a network interface +---------------------------------------- +.. index:: ifconfig + +**SYNOPSYS:** + +.. code:: c + + 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. + +**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 ``ifconfig``: +.. code:: c + + ************ 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 + +**CONFIGURATION:** + +.. 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. + +This command can be excluded from the shell command set by +defining ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all +shell commands have been configured. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ifconfig + +The ``ifconfig`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ifconfig( + int argc, + char \**argv + ); + +The configuration structure for the ``ifconfig`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command; + +route - show or manipulate the ip routing table +----------------------------------------------- +.. index:: route + +**SYNOPSYS:** + +.. code:: c + + 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:: c + + 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:: c + + [/] $ 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_route + +The ``route`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_route( + int argc, + char \**argv + ); + +The configuration structure for the ``route`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_ROUTE_Command; + +ping - ping a host or IP address +-------------------------------- +.. index:: ping + +**SYNOPSYS:** + +.. code:: c + + 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. + +**EXAMPLES:** + +The following is an example of how to use ``oing`` to ping: +.. code:: c + + [/] # 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:** + +.. 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. + +**PROGRAMMING INFORMATION:** + +.. index:: rtems_shell_rtems_main_ping + +The ``ping`` is implemented by a C language function +which has the following prototype: +.. code:: c + + int rtems_shell_rtems_main_ping( + int argc, + char \**argv + ); + +The configuration structure for the ``ping`` has the +following prototype: +.. code:: c + + extern rtems_shell_cmd_t rtems_shell_PING_Command; + +Function and Variable Index +########################### + +.. COMMENT: There are currently no Command and Variable Index entries. + +Concept Index +############# + +Command Index +############# + -- cgit v1.2.3