3. General Commands — RTEMS Shell Guide 5.4-rc2 (21st August 2026) documentation

# 3. General Commands

## 3.1. 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

## 3.2. 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.

### 3.2.1. help - Print command help

SYNOPSYS:

      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`:

      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.

### 3.2.2. alias - add alias for an existing command

SYNOPSYS:

      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`:

      SHLL [/] $ me
      shell:me command not found
      SHLL [/] $ alias whoami me
      SHLL [/] $ me
      rtems
      SHLL [/] $ whoami
      rtems

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_ALIAS` to have this command included.

  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:

  The `alias` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_alias(
          int    argc,
          char **argv
      );

  The configuration structure for the `alias` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;

### 3.2.3. cmdls - List commands

SYNOPSYS:

      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`:

      SHLL [/] # cmdls help shutdown
      r-xr-xr-x     0     0 help
      r-x------     0     0 shutdown

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_CMDLS` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_CMDLS` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The configuration structure for the `cmdls` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_CMDLS_Command;

### 3.2.4. cmdchown - Change user or owner of commands

SYNOPSYS:

      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`:

      [/] # cmdls help
      r-xr-xr-x     0     0 help
      [/] # cmdchown 1:1 help
      [/] # cmdls help
      r--r--r--     1     1 help

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_CMDCHOWN` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The configuration structure for the `cmdchown` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command;

### 3.2.5. cmdchmod - Change mode of commands

SYNOPSYS:

      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`:

      [/] # cmdls help
      r-xr-xr-x     0     0 help
      [/] # cmdchmod 544 help
      [/] # cmdls help
      r-xr--r--     0     0 help

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_CMDCHMOD` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The configuration structure for the `cmdchmod` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command;

### 3.2.6. date - print or set current date and time

SYNOPSYS:

      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:

  None.

EXAMPLES:

  The following is an example of how to use `date`:

      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:

  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:

  The `date` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_date(
          int    argc,
          char **argv
      );

  The configuration structure for the `date` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_DATE_Command;

### 3.2.7. echo - produce message in a shell script

SYNOPSYS:

      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 language 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`:

      SHLL [/] $ echo a b c
      a b c
      SHLL [/] $ echo

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_ECHO` to have this command included.

  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:

  The `echo` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_echo(
          int    argc,
          char **argv
      );

  The configuration structure for the `echo` has the following prototype:

      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.

### 3.2.8. sleep - delay for a specified amount of time

SYNOPSYS:

      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`:

      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:

  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:

  The `sleep` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_sleep(
          int    argc,
          char **argv
      );

  The configuration structure for the `sleep` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_SLEEP_Command;

### 3.2.9. id - show uid gid euid and egid

SYNOPSYS:

      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`:

      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:

      SHLL [/] # id
      uid=0(root),gid=0(root),euid=0(root),egid=0(root)

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_ID` to have this command included.

  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:

  The `id` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_id(
          int    argc,
          char **argv
      );

  The configuration structure for the `id` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_ID_Command;

### 3.2.10. tty - show ttyname

SYNOPSYS:

      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`:

      SHLL [/] $ tty
      /dev/console

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_TTY` to have this command included.

  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:

  The `tty` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_tty(
          int    argc,
          char **argv
      );

  The configuration structure for the `tty` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_TTY_Command;

### 3.2.11. whoami - print effective user id

SYNOPSYS:

      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`:

      SHLL [/] $ whoami
      rtems

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_WHOAMI` to have this command included.

  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:

  The `whoami` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_whoami(
          int    argc,
          char **argv
      );

  The configuration structure for the `whoami` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command;

### 3.2.12. getenv - print environment variable

SYNOPSYS:

      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`:

      SHLL [/] $ getenv BASEPATH
      /mnt/hda1

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_GETENV` to have this command included.

  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:

  The `getenv` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_getenv(
          int    argc,
          char **argv
      );

  The configuration structure for the `getenv` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_GETENV_Command;

### 3.2.13. setenv - set environment variable

SYNOPSYS:

      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`:

      SHLL [/] $ setenv BASEPATH /mnt/hda1

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_SETENV` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_SETENV` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The `setenv` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_setenv(
          int    argc,
          char **argv
      );

  The configuration structure for the `setenv` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_SETENV_Command;

### 3.2.14. unsetenv - unset environment variable

SYNOPSYS:

      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`:

      SHLL [/] $ unsetenv BASEPATH

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_UNSETENV` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_UNSETENV` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The `unsetenv` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_unsetenv(
          int    argc,
          char **argv
      );

  The configuration structure for the `unsetenv` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command;

### 3.2.15. time - time command execution

SYNOPSYS:

      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`:

      SHLL [/] $ time cp -r /nfs/directory /c

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_TIME` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_TIME` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The `time` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_time(
          int    argc,
          char **argv
      );

  The configuration structure for the `time` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_TIME_Command;

### 3.2.16. logoff - logoff from the system

SYNOPSYS:

      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`:

      SHLL [/] $ logoff
      logoff from the system...

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_LOGOFF` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_LOGOFF` when all shell commands have been configured.

PROGRAMMING INFORMATION:

  The `logoff` is implemented by a C language function which has the following prototype:

      int rtems_shell_rtems_main_logoff(
          int    argc,
          char **argv
      );

  The configuration structure for the `logoff` has the following prototype:

      extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command;

### 3.2.17. rtc - RTC driver configuration

SYNOPSYS:

      rtc

CONFIGURATION:

  This command is included in the default shell command set. When building a custom command set, define `CONFIGURE_SHELL_COMMAND_RTC` to have this command included.

  This command can be excluded from the shell command set by defining `CONFIGURE_SHELL_NO_COMMAND_RTC` when all shell commands have been configured.

### 3.2.18. exit - exit the shell

SYNOPSYS:

      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`:

      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.