@c
@c COPYRIGHT (c) 1988-2010.
@c On-Line Applications Research Corporation (OAR).
@c All rights reserved.
@c
@c $Id$
@c
@chapter General Commands
@section Introduction
The RTEMS shell has the following general commands:
@itemize @bullet
@item @code{alias} - Add alias for an existing command
@item @code{date} - Print or set current date and time
@item @code{echo} - Produce message in a shell script
@item @code{sleep} - Delay for a specified amount of time
@item @code{id} - show uid gid euid and egid
@item @code{tty} - show ttyname
@item @code{whoami} - print effective user id
@item @code{getenv} - print environment variable
@item @code{setenv} - set environment variable
@item @code{unsetenv} - unset environment variable
@item @code{time} - time command execution
@item @code{logoff} - logoff from the system
@item @code{rtc} - RTC driver configuration
@item @code{exit} - alias for logoff command
@end itemize
@section 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.
@c
@c
@c
@page
@subsection alias - add alias for an existing command
@pgindex alias
@subheading SYNOPSYS:
@example
alias oldCommand newCommand
@end example
@subheading DESCRIPTION:
This command adds an alternate name for an existing command to
the command set.
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
NONE
@subheading EXAMPLES:
The following is an example of how to use @code{alias}:
@example
SHLL [/] $ me
shell:me command not found
SHLL [/] $ alias whoami me
SHLL [/] $ me
rtems
SHLL [/] $ whoami
rtems
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_ALIAS
@findex CONFIGURE_SHELL_COMMAND_ALIAS
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_ALIAS} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_ALIAS} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_alias
The @code{alias} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_alias(
int argc,
char **argv
);
@end example
The configuration structure for the @code{alias} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;
@end example
@c
@c
@c
@page
@subsection date - print or set current date and time
@pgindex date
@subheading SYNOPSYS:
@example
date
date DATE TIME
@end example
@subheading DESCRIPTION:
This command operates one of two modes. When invoked with no
arguments, it prints the current date and time. When invoked
with both @code{date} and @code{time} arguments, it sets the
current time.
The @code{date} is specified in @code{YYYY-MM-DD} format.
The @code{time} is specified in @code{HH:MM:SS} format.
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
This comm
@subheading EXAMPLES:
The following is an example of how to use @code{date}:
@example
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
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_DATE
@findex CONFIGURE_SHELL_COMMAND_DATE
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_DATE} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_DATE} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_date
The @code{date} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_date(
int argc,
char **argv
);
@end example
The configuration structure for the @code{date} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_DATE_Command;
@end example
@c
@c
@c
@page
@subsection echo - produce message in a shell script
@pgindex echo
@subheading SYNOPSYS:
@example
echo [-n | -e] args ...
@end example
@subheading DESCRIPTION:
echo prints its arguments on the standard output, separated by spaces.
Unless the @b{-n} option is present, a newline is output following the
arguments. The @b{-e} option causes echo to treat the escape sequences
specially, as described in the following paragraph. The @b{-e} option is the
default, and is provided solely for compatibility with other systems.
Only one of the options @b{-n} and @b{-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:
@table @b
@item \b
A backspace character is output.
@item \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.
@item \f
Output a form feed.
@item \n
Output a newline character.
@item \r
Output a carriage return.
@item \t
Output a (horizontal) tab character.
@item \v
Output a vertical tab.
@item \0digits
Output the character whose value is given by zero to three digits.
If there are zero digits, a nul character is output.
@item \\
Output a backslash.
@end table
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
The octal character escape mechanism (\0digits) differs from the C lan-
guage mechanism.
There is no way to force @code{echo} to treat its arguments literally, rather
than interpreting them as options and escape sequences.
@subheading EXAMPLES:
The following is an example of how to use @code{echo}:
@example
SHLL [/] $ echo a b c
a b c
SHLL [/] $ echo
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_ECHO
@findex CONFIGURE_SHELL_COMMAND_ECHO
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_ECHO} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_ECHO} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_echo
The @code{echo} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_echo(
int argc,
char **argv
);
@end example
The configuration structure for the @code{echo} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_ECHO_Command;
@end example
@subheading ORIGIN:
The implementation and portions of the documentation for this
command are from NetBSD 4.0.
@c
@c
@c
@page
@subsection sleep - delay for a specified amount of time
@pgindex sleep
@subheading SYNOPSYS:
@example
sleep seconds
sleep seconds nanoseconds
@end example
@subheading DESCRIPTION:
This command causes the task executing the shell to block
for the specified number of @code{seconds} and @code{nanoseconds}.
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
This command is implemented using the @code{nanosleep()} method.
The command line interface is similar to the @code{sleep} command
found on POSIX systems but the addition of the @code{nanoseconds}
parameter allows fine grained delays in shell scripts without
adding another command such as @code{usleep}.
@subheading EXAMPLES:
The following is an example of how to use @code{sleep}:
@example
SHLL [/] $ sleep 10
SHLL [/] $ sleep 0 5000000
@end example
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.
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_SLEEP
@findex CONFIGURE_SHELL_COMMAND_SLEEP
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_SLEEP} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_SLEEP} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_sleep
The @code{sleep} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_sleep(
int argc,
char **argv
);
@end example
The configuration structure for the @code{sleep} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_SLEEP_Command;
@end example
@c
@c
@c
@page
@subsection id - show uid gid euid and egid
@pgindex id
@subheading SYNOPSYS:
@example
id
@end example
@subheading 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).
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading 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.
@subheading EXAMPLES:
The first example of the @code{id} command is from a session logged
in as the normal user @code{rtems}:
@example
SHLL [/] # id
uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems)
@end example
The second example of the @code{id} command is from a session logged
in as the @code{root} user:
@example
SHLL [/] # id
uid=0(root),gid=0(root),euid=0(root),egid=0(root)
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_ID
@findex CONFIGURE_SHELL_COMMAND_ID
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_ID} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_ID} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_id
The @code{id} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_id(
int argc,
char **argv
);
@end example
The configuration structure for the @code{id} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_ID_Command;
@end example
@c
@c
@c
@page
@subsection tty - show ttyname
@pgindex tty
@subheading SYNOPSYS:
@example
tty
@end example
@subheading DESCRIPTION:
This command prints the file name of the device connected
to standard input.
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
NONE
@subheading EXAMPLES:
The following is an example of how to use @code{tty}:
@example
SHLL [/] $ tty
/dev/console
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_TTY
@findex CONFIGURE_SHELL_COMMAND_TTY
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_TTY} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_TTY} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_tty
The @code{tty} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_tty(
int argc,
char **argv
);
@end example
The configuration structure for the @code{tty} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_TTY_Command;
@end example
@c
@c
@c
@page
@subsection whoami - print effective user id
@pgindex whoami
@subheading SYNOPSYS:
@example
whoami
@end example
@subheading DESCRIPTION:
This command displays the user name associated with the current
effective user id.
@subheading EXIT STATUS:
This command always succeeds.
@subheading NOTES:
NONE
@subheading EXAMPLES:
The following is an example of how to use @code{whoami}:
@example
SHLL [/] $ whoami
rtems
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_WHOAMI
@findex CONFIGURE_SHELL_COMMAND_WHOAMI
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_WHOAMI} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_WHOAMI} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_whoami
The @code{whoami} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_whoami(
int argc,
char **argv
);
@end example
The configuration structure for the @code{whoami} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command;
@end example
@c
@c
@c
@page
@subsection getenv - print environment variable
@pgindex getenv
@subheading SYNOPSYS:
@example
getenv variable
@end example
@subheading DESCRIPTION:
This command is used to display the value of a @code{variable} in the set
of environment variables.
@subheading EXIT STATUS:
This command will return 1 and print a diagnostic message if
a failure occurs.
@subheading NOTES:
The entire RTEMS application shares a single set of environment variables.
@subheading EXAMPLES:
The following is an example of how to use @code{getenv}:
@example
SHLL [/] $ getenv BASEPATH
/mnt/hda1
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_GETENV
@findex CONFIGURE_SHELL_COMMAND_GETENV
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_GETENV} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_GETENV} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_getenv
The @code{getenv} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_getenv(
int argc,
char **argv
);
@end example
The configuration structure for the @code{getenv} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_GETENV_Command;
@end example
@c
@c
@c
@page
@subsection setenv - set environment variable
@pgindex setenv
@subheading SYNOPSYS:
@example
setenv variable [value]
@end example
@subheading DESCRIPTION:
This command is used to add a new @code{variable} to the set of environment
variables or to modify the variable of an already existing @code{variable}.
If the @code{value} is not provided, the @code{variable} will be set to the
empty string.
@subheading EXIT STATUS:
This command will return 1 and print a diagnostic message if
a failure occurs.
@subheading NOTES:
The entire RTEMS application shares a single set of environment variables.
@subheading EXAMPLES:
The following is an example of how to use @code{setenv}:
@example
SHLL [/] $ setenv BASEPATH /mnt/hda1
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_SETENV
@findex CONFIGURE_SHELL_COMMAND_SETENV
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_SETENV} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_SETENV} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_setenv
The @code{setenv} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_setenv(
int argc,
char **argv
);
@end example
The configuration structure for the @code{setenv} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_SETENV_Command;
@end example
@c
@c
@c
@page
@subsection unsetenv - unset environment variable
@pgindex unsetenv
@subheading SYNOPSYS:
@example
unsetenv variable
@end example
@subheading DESCRIPTION:
This command is remove to a @code{variable} from the set of environment
variables.
@subheading EXIT STATUS:
This command will return 1 and print a diagnostic message if
a failure occurs.
@subheading NOTES:
The entire RTEMS application shares a single set of environment variables.
@subheading EXAMPLES:
The following is an example of how to use @code{unsetenv}:
@example
SHLL [/] $ unsetenv BASEPATH
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_UNSETENV
@findex CONFIGURE_SHELL_COMMAND_UNSETENV
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_UNSETENV} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_UNSETENV} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_unsetenv
The @code{unsetenv} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_unsetenv(
int argc,
char **argv
);
@end example
The configuration structure for the @code{unsetenv} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command;
@end example
@c
@c
@c
@page
@subsection time - time command execution
@pgindex time
@subheading SYNOPSYS:
@example
time command [argument ...]
@end example
@subheading DESCRIPTION:
The time command executes and times a command. After the command
finishes, time writes the total time elapsed. Times are reported in
seconds.
@subheading EXIT STATUS:
This command returns 0 on success and non-zero if an error is encountered.
@subheading NOTES:
None.
@subheading EXAMPLES:
The following is an example of how to use @code{time}:
@example
SHLL [/] $ time cp -r /nfs/directory /c
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_TIME
@findex CONFIGURE_SHELL_COMMAND_TIME
This command is included in the default shell command set. When
building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_TIME} to have this command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_TIME} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_time
The @code{time} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_time(
int argc,
char **argv
);
@end example
The configuration structure for the @code{time} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_TIME_Command;
@end example
@c
@c
@c
@page
@subsection logoff - logoff from the system
@pgindex logoff
@subheading SYNOPSYS:
@example
logoff
@end example
@subheading DESCRIPTION:
This command logs the user out of the shell.
@subheading EXIT STATUS:
This command does not return.
@subheading 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.
@subheading EXAMPLES:
The following is an example of how to use @code{logoff}:
@example
SHLL [/] $ logoff
logoff from the system...
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_LOGOFF
@findex CONFIGURE_SHELL_COMMAND_LOGOFF
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_LOGOFF} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_LOGOFF} when all
shell commands have been configured.
@subheading PROGRAMMING INFORMATION:
@findex rtems_shell_rtems_main_logoff
The @code{logoff} is implemented by a C language function
which has the following prototype:
@example
int rtems_shell_rtems_main_logoff(
int argc,
char **argv
);
@end example
The configuration structure for the @code{logoff} has the
following prototype:
@example
extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command;
@end example
@c
@c
@c
@page
@subsection rtc - RTC driver configuration
@pgindex rtc
@subheading SYNOPSYS:
@example
rtc
@end example
@subheading CONFIGURATION:
@findex CONFIGURE_SHELL_NO_COMMAND_RTC
@findex CONFIGURE_SHELL_COMMAND_RTC
This command is included in the default shell command set.
When building a custom command set, define
@code{CONFIGURE_SHELL_COMMAND_RTC} to have this
command included.
This command can be excluded from the shell command set by
defining @code{CONFIGURE_SHELL_NO_COMMAND_RTC} when all
shell commands have been configured.
@c
@c
@c
@page
@subsection exit - exit the shell
@pgindex exit
@subheading SYNOPSYS:
@example
exit
@end example
@subheading DESCRIPTION:
This command causes the shell interpreter to @code{exit}.
@subheading EXIT STATUS:
This command does not return.
@subheading NOTES:
In contrast to @ref{General Commands logoff - logoff from the system, logoff},
this command is built into the shell interpreter loop.
@subheading EXAMPLES:
The following is an example of how to use @code{exit}:
@example
SHLL [/] $ exit
Shell exiting
@end example
@subheading CONFIGURATION:
This command is always present and cannot be disabled.
@subheading PROGRAMMING INFORMATION:
The @code{exit} is implemented directly in the shell interpreter.
There is no C routine associated with it.