source: rtems-docs/shell/shell.rst @ 5daabd2

4.115
Last change on this file since 5daabd2 was 5daabd2, checked in by Amar Takhar <amar@…>, on 01/16/16 at 04:41:06

Initial reST documentation using Sphinx.

  • Property mode set to 100644
File size: 192.2 KB
Line 
1:orphan:
2
3
4.. COMMENT: %**end of header
5
6.. COMMENT: COPYRIGHT (c) 1989-2013.
7
8.. COMMENT: On-Line Applications Research Corporation (OAR).
9
10.. COMMENT: All rights reserved.
11
12.. COMMENT: Master file for the Shell User's Guide
13
14.. COMMENT: Joel's Questions
15
16.. COMMENT: 1.  Why does paragraphindent only impact makeinfo?
17
18.. COMMENT: 2.  Why does paragraphindent show up in HTML?
19
20.. COMMENT: COPYRIGHT (c) 1988-2002.
21
22.. COMMENT: On-Line Applications Research Corporation (OAR).
23
24.. COMMENT: All rights reserved.
25
26.. COMMENT: The following determines which set of the tables and figures we will use.
27
28.. COMMENT: We default to ASCII but if available TeX or HTML versions will
29
30.. COMMENT: be used instead.
31
32.. COMMENT: @clear use-html
33
34.. COMMENT: @clear use-tex
35
36.. COMMENT: The following variable says to use texinfo or html for the two column
37
38.. COMMENT: texinfo tables.  For somethings the format does not look good in html.
39
40.. COMMENT: With our adjustment to the left column in TeX, it nearly always looks
41
42.. COMMENT: good printed.
43
44.. COMMENT: Custom whitespace adjustments.  We could fiddle a bit more.
45
46.. COMMENT: @syncodeindex fn cp
47
48.. COMMENT: Title Page Stuff
49
50.. COMMENT: I don't really like having a short title page.  -joel
51
52.. COMMENT: @shorttitlepage RTEMS Shell User's Guide
53
54========================
55RTEMS Shell User’s Guide
56========================
57
58.. COMMENT: COPYRIGHT (c) 1988-2015.
59
60.. COMMENT: On-Line Applications Research Corporation (OAR).
61
62.. COMMENT: All rights reserved.
63
64.. COMMENT: The following puts a space somewhere on an otherwise empty page so we
65
66.. COMMENT: can force the copyright description onto a left hand page.
67
68COPYRIGHT © 1988 - 2015.
69
70On-Line Applications Research Corporation (OAR).
71
72The authors have used their best efforts in preparing
73this material.  These efforts include the development, research,
74and testing of the theories and programs to determine their
75effectiveness.  No warranty of any kind, expressed or implied,
76with regard to the software or the material contained in this
77document is provided.  No liability arising out of the
78application or use of any product described in this document is
79assumed.  The authors reserve the right to revise this material
80and to make changes from time to time in the content hereof
81without obligation to notify anyone of such revision or changes.
82
83The RTEMS Project is hosted at http://www.rtems.org.  Any
84inquiries concerning RTEMS, its related support components, or its
85documentation should be directed to the Community Project hosted athttp://www.rtems.org.
86
87Any inquiries for commercial services including training, support, custom
88development, application development assistance should be directed tohttp://www.rtems.com.
89
90.. COMMENT: This prevents a black box from being printed on "overflow" lines.
91
92.. COMMENT: The alternative is to rework a sentence to avoid this problem.
93
94RTEMS Shell User’s Guide
95########################
96
97.. COMMENT: COPYRIGHT (c) 1989-2011.
98
99.. COMMENT: On-Line Applications Research Corporation (OAR).
100
101.. COMMENT: All rights reserved.
102
103Preface
104#######
105
106Real-time embedded systems vary widely based upon their
107operational and maintenance requirements. Some of these
108systems provide ways for the user or developer to interact
109with them.  This interaction could be used for operational,
110diagnostic, or configuration purposes.  The capabilities
111described in this manual are those provided with RTEMS to
112provide a command line interface for user access.  Some
113of these commands will be familiar as standard POSIX utilities
114while others are RTEMS specific or helpful in debugging
115and analyzing an embedded system. As a simple example of
116the powerful and very familiar capabilities that the RTEMS
117Shell provides to an application, consider the following
118example which hints at some of the capabilities available:
119.. code:: c
120
121    Welcome to rtems-4.10.99.0(SPARC/w/FPU/sis)
122    COPYRIGHT (c) 1989-2011.
123    On-Line Applications Research Corporation (OAR).
124    Login into RTEMS
125    login: rtems
126    Password:
127    RTEMS SHELL (Ver.1.0-FRC):/dev/console. Feb 28 2008. 'help' to list commands.
128    SHLL \[/] $ cat /etc/passwd
129    root:\*:0:0:root::/:/bin/sh
130    rtems:\*:1:1:RTEMS Application::/:/bin/sh
131    tty:!:2:2:tty owner::/:/bin/false
132    SHLL \[/] $ ls /dev
133    -rwxr-xr-x   1  rtems   root           0 Jan 01 00:00 console
134    -rwxr-xr-x   1   root   root           0 Jan 01 00:00 console_b
135    2 files 0 bytes occupied
136    SHLL \[/] $ stackuse
137    Stack usage by thread
138    ID      NAME    LOW          HIGH     CURRENT     AVAILABLE     USED
139    0x09010001  IDLE 0x023d89a0 - 0x023d99af 0x023d9760      4096        608
140    0x0a010001  UI1  0x023d9f30 - 0x023daf3f 0x023dad18      4096       1804
141    0x0a010002  SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0     16384       6204
142    0xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
143    SHLL \[/] $ mount -L
144    File systems: msdos
145    SHLL \[/] $
146
147In the above example, the user *rtems* logs into a
148SPARC based RTEMS system.  The first command is ``cat /etc/passwd``.  This simple command lets us
149know that this application is running the In Memory
150File System (IMFS) and that the infrastructure has
151provided dummy entries for */etc/passwd* and a few
152other files.  The contents of */etc/passwd* let
153us know that the user could have logged in as ``root``.
154In fact, the ``root`` user has more permissions
155than ``rtems`` who is not allowed to write into the
156filesystem.
157
158The second command is ``ls /dev`` which lets us
159know that RTEMS has POSIX-style device nodes which
160can be accesses through standard I/O function calls.
161
162The third command executed is the RTEMS specific ``stackuse`` which gives a report on the stack
163usage of each thread in the system.  Since stack
164overflows are a common error in deeply embedded systems,
165this is a surprising simple, yet powerful debugging aid.
166
167Finally, the last command, ``mount -L`` hints that
168RTEMS supports a variety of mountable filesystems. With
169support for MS-DOS FAT on IDE/ATA and Flash devices as
170well as network-based filesystens such as NFS and TFTP,
171the standard free RTEMS provides a robuse infrastructure
172for embedded applications.
173
174This manual describes the RTEMS Shell and its command set.
175In our terminology, the Shell is just a loop reading user
176input and turning that input into commands with argument.
177The Shell provided with RTEMS is a simple command reading
178loop with limited scripting capabilities.  It can be connected
179to via a standard serial port or connected to the RTEMS``telnetd`` server for use across a network.
180
181Each command in the command set is implemented as a single
182subroutine which has a *main-style* prototype.  The commands
183interpret their arguments and operate upon stdin, stdout, and
184stderr by default.  This allows each command to be invoked
185independent of the shell.
186
187The described separation of shell from commands from communications
188mechanism was an important design goal.  At one level, the RTEMS
189Shell is a complete shell environment providing access to multiple
190POSIX compliant filesystems and TCP/IP stack.  The subset of
191capabilities available is easy to configure and the standard
192Shell can be logged into from either a serial port or via telnet.
193But at another level, the Shell is a large set of components which
194can be integrated into the user’s developed command interpreter.
195In either case, it is trivial to add custom commands to the command
196set available.
197
198Acknowledgements
199================
200
201.. COMMENT: COPYRIGHT (c) 1988-2009.
202
203.. COMMENT: On-Line Applications Research Corporation (OAR).
204
205.. COMMENT: All rights reserved.
206
207.. COMMENT: The RTEMS Project has been granted permission from The Open Group
208
209.. COMMENT: IEEE to excerpt and use portions of the POSIX standards documents
210
211.. COMMENT: in the RTEMS POSIX API User's Guide and RTEMS Shell User's Guide.
212
213.. COMMENT: We have to include a specific acknowledgement paragraph in these
214
215.. COMMENT: documents (e.g. preface or copyright page) and another slightly
216
217.. COMMENT: different paragraph for each manual page that excerpts and uses
218
219.. COMMENT: text from the standards.
220
221.. COMMENT: This file should help ensure that the paragraphs are consistent
222
223.. COMMENT: and not duplicated
224
225    The Institute of Electrical and Electronics Engineers, Inc and The
226    Open Group, have given us permission to reprint portions of their
227    documentation.
228    Portions of this text are reprinted and reproduced in electronic
229    form from IEEE Std 1003.1, 2004 Edition, Standard for Information
230    Technology — Operating System Interface (POSIX), The Open
231    Group Base Specifications Issue 6, Copyright © 2001-2004 by the
232    Institute of Electrical and Electronics Engineers, Inc and The
233    Open Group. In the event of any discrepancy between this version
234    and the original IEEE and The Open Group Standard, the original
235    IEEE and The Open Group Standard is the referee document. The
236    original Standard can be obtained online athttp://www.opengroup.org/unix/online.html.
237    This notice shall appear on any product containing this material.
238
239.. COMMENT: COPYRIGHT (c) 1988-2008.
240
241.. COMMENT: On-Line Applications Research Corporation (OAR).
242
243.. COMMENT: All rights reserved.
244
245Configuration and Initialization
246################################
247
248Introduction
249============
250
251This chapter provides information on how the application
252configures and initializes the RTEMS shell.
253
254Configuration
255=============
256
257The command set available to the application is user configurable.
258It is configured using a mechanism similar to the ``confdefs.h``
259mechanism used to specify application configuration.
260
261In the simplest case, if the user wishes to configure a command
262set with all commands available that are neither filesystem
263management (e.g. mounting, formating, etc.) or network related,
264then the following is all that is required:
265.. code:: c
266
267    #define CONFIGURE_SHELL_COMMANDS_INIT
268    #define CONFIGURE_SHELL_COMMANDS_ALL
269    #include <rtems/shellconfig.h>
270
271In a slightly more complex example, if the user wishes to include
272all networking commands as well as support for mounting MS-DOS and
273NFS filesystems, then the following is all that is required:
274.. code:: c
275
276    #define CONFIGURE_SHELL_COMMANDS_INIT
277    #define CONFIGURE_SHELL_COMMANDS_ALL
278    #define CONFIGURE_SHELL_MOUNT_MSDOS
279    #define CONFIGURE_SHELL_MOUNT_NFS
280    #include <rtems/shellconfig.h>
281
282Customizing the Command Set
283---------------------------
284
285The user can configure specific command sets by either building
286up the set from individual commands or starting with a complete
287set and disabling individual commands.  Each command has two
288configuration macros associated with it.
289
290*``CONFIGURE_SHELL_COMMAND_XXX``*
291    Each command has a constant of this form which is defined when
292    building a command set by individually enabling specific
293    commands.
294
295*``CONFIGURE_SHELL_NO_COMMAND_XXX``*
296    In contrast, each command has a similar command which is
297    defined when the application is configuring a command set
298    by disabling specific commands in the set.
299
300Adding Custom Commands
301----------------------
302
303One of the design goals of the RTEMS Shell was to make it
304easy for a user to add custom commands specific to their
305application.  We believe this design goal was accomplished.
306In order to add a custom command, the user is required to
307do the following:
308
309- Provide a *main-style* function which implements
310  the command.  If that command function uses a ``getopt``
311  related function to parse arguments, it *MUST* use the
312  reentrant form.
313
314- Provide a command definition structure of type``rtems_shell_cmd_t``.
315
316- Configure that command using the``CONFIGURE_SHELL_USER_COMMANDS`` macro.
317
318Custom aliases are configured similarly but the user
319only provides an alias definition structure of type``rtems_shell_alias_t`` and configures the alias
320via the ``CONFIGURE_SHELL_USER_ALIASES`` macro.
321
322In the following example, we have implemented a custom
323command named ``usercmd`` which simply prints the
324arguments it was passed. We have also provided an
325alias for ``usercmd`` named ``userecho``.
326.. code:: c
327
328    #include <rtems/shell.h>
329    int main_usercmd(int argc, char \**argv)
330    {
331    int i;
332    printf( "UserCommand: argc=%d\\n", argc );
333    for (i=0 ; i<argc ; i++ )
334    printf( "argv[%d]= %s\\n", i, argv[i] );
335    return 0;
336    }
337    rtems_shell_cmd_t Shell_USERCMD_Command = {
338    "usercmd",                  /* name \*/
339    "usercmd n1 \[n2 \[n3...]]",  /* usage \*/
340    "user",                     /* topic \*/
341    main_usercmd,               /* command \*/
342    NULL,                       /* alias \*/
343    NULL                        /* next \*/
344    };
345    rtems_shell_alias_t Shell_USERECHO_Alias = {
346    "usercmd",                  /* command \*/
347    "userecho"                  /* alias \*/
348    };
349    #define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command
350    #define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias
351    #define CONFIGURE_SHELL_COMMANDS_INIT
352    #define CONFIGURE_SHELL_COMMANDS_ALL
353    #define CONFIGURE_SHELL_MOUNT_MSDOS
354    #include <rtems/shellconfig.h>
355
356Notice in the above example, that the user wrote the*main* for their command (e.g. ``main_usercmd``)
357which looks much like any other ``main()``.  They
358then defined a ``rtems_shell_cmd_t`` structure
359named ``Shell_USERCMD_Command`` which describes that
360command.  This command definition structure is registered
361into the static command set by defining``CONFIGURE_SHELL_USER_COMMANDS`` to``&Shell_USERCMD_Command``.
362
363Similarly, to add the ``userecho`` alias, the user
364provides the alias definition structure named``Shell_USERECHO_Alias`` and defines``CONFIGURE_SHELL_USER_ALIASES`` to configure
365the alias.
366
367The user can configure any number of commands
368and aliases in this manner.
369
370Initialization
371==============
372
373The shell may be easily attached to a serial port or
374to the ``telnetd`` server.  This section describes
375how that is accomplished.
376
377Attached to a Serial Port
378-------------------------
379
380Starting the shell attached to the console or a serial
381port is very simple. The user invokes ``rtems_shell_init``
382with parameters to indicate the characteristics of the task
383that will be executing the shell including name, stack size,
384and priority.  The user also specifies the device that the
385shell is to be attached to.
386
387This example is taken from the ``fileio`` sample test.
388This shell portion of this test can be run on any target which
389provides a console with input and output capabilities.  It does
390not include any commands which cannot be supported on all BSPs.
391The source code for this test is in ``testsuites/samples/fileio``
392with the shell configuration in the ``init.c`` file.
393.. code:: c
394
395    #include <rtems/shell.h>
396    void start_shell(void)
397    {
398    printf(" =========================\\n");
399    printf(" starting shell\\n");
400    printf(" =========================\\n");
401    rtems_shell_init(
402    "SHLL",                       /* task name \*/
403    RTEMS_MINIMUM_STACK_SIZE * 4, /* task stack size \*/
404    100,                          /* task priority \*/
405    "/dev/console",               /* device name \*/
406    false,                        /* run forever \*/
407    true,                         /* wait for shell to terminate \*/
408    rtems_shell_login_check       /* login check function,
409    use NULL to disable a login check \*/
410    );
411    }
412
413In the above example, the call to ``rtems_shell_init``
414spawns a task to run the RTEMS Shell attached to ``/dev/console``
415and executing at priority 100.  The caller suspends itself and
416lets the shell take over the console device.  When the shell
417is exited by the user, then control returns to the caller.
418
419Attached to a Socket
420--------------------
421
422TBD
423
424Access Control
425==============
426
427Login Checks
428------------
429
430Login checks are optional for the RTEMS shell and can be configured via a login
431check handler passed to ``rtems_shell_init()``.  One login check handler is``rtems_shell_login_check()``.
432
433Configuration Files
434-------------------
435
436The following files are used by the login check handler``rtems_shell_login_check()`` to validate a passphrase for a user and to set
437up the user environment for the shell command execution.
438
439:file:`/etc/passwd`
440    The format for each line is
441    .. code:: c
442        user_name:password:UID:GID:GECOS:directory:shell
443    with colon separated
444    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
445    password allows login without a password for this user.  In contrast to
446    standard UNIX systems, this file is only readable and writeable for the user
447    with an UID of zero by default.  The ``directory`` is used to perform a
448    filesystem change root operation in ``rtems_shell_login_check()`` in
449    contrast to a normal usage as the HOME directory of the user.  The*default* content is
450    .. code:: c
451        root::0:0::::
452    so there is *no password required* for the ``root`` user.
453
454:file:`/etc/group`
455    The format for each line is
456    .. code:: c
457        group_name:password:GID:user_list
458    with colon separated fields.  The ``user_list`` is comma separated.  For
459    more information refer to the Linux GROUP(5) man page.  In contrast to standard
460    UNIX systems, this file is only readable and writeable for the user with an UID
461    of zero by default.  The default content is
462    .. code:: c
463        root::0:
464
465Command Visibility and Execution Permission
466-------------------------------------------
467
468Each command has
469
470- an owner,
471
472- a group, and
473
474- a read permission flag for the owner, the group and all other users, and
475
476- an execution permission flag for the owner, the group and all other
477  users.
478
479The read and write permission flags are stored in the command mode.  The read
480permission flags determine the visibility of the command for the current user.
481The execution permission flags determine the ability to execute a command for
482the current user.  These command properties can be displayed and changed with
483the
484
485- ``cmdls``,
486
487- ``cmdchown``, and
488
489- ``cmdchmod``
490
491commands.  The access is determined by the effective UID, the effective GID and
492the supplementary group IDs of the current user and follows the standard
493filesystem access procedure.
494
495Add CRYPT(3) Formats
496--------------------
497
498By 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
499available out of the box
500
501- ``crypt_md5_format``,
502
503- ``crypt_sha256_format``, and
504
505- ``crypt_sha512_format``.
506
507An example follows... index:: crypt_add_format
508
509.. code:: c
510
511    #include <crypt.h>
512    void add_formats( void )
513    {
514    crypt_add_format( &crypt_md5_format );
515    crypt_add_format( &crypt_sha512_format );
516    }
517
518Functions
519=========
520
521This section describes the Shell related C functions which are
522publicly available related to initialization and configuration.
523
524rtems_shell_init - Initialize the shell
525---------------------------------------
526.. index:: initialization
527
528**CALLING SEQUENCE:**
529
530.. index:: rtems_shell_init
531
532.. code:: c
533
534    rtems_status_code rtems_shell_init(
535    const char          \*task_name,
536    size_t               task_stacksize,
537    rtems_task_priority  task_priority,
538    const char          \*devname,
539    bool                 forever,
540    bool                 wait,
541    rtems_login_check    login_check
542    );
543
544**DIRECTIVE STATUS CODES:**
545
546``RTEMS_SUCCESSFUL`` - Shell task spawned successfully
547
548others - to indicate a failure condition
549
550**DESCRIPTION:**
551
552This service creates a task with the specified characteristics to
553run the RTEMS Shell attached to the specified ``devname``.
554
555**NOTES:**
556
557This method invokes the ``rtems_task_create`` and ``rtems_task_start``
558directives and as such may return any status code that those directives
559may return.
560
561There is one POSIX key necessary for all shell instances together and one POSIX
562key value pair per instance. You should make sure that your RTEMS configuration
563accounts for these resources.
564
565rtems_shell_login_check - Default login check handler
566-----------------------------------------------------
567.. index:: initialization
568
569**CALLING SEQUENCE:**
570
571.. index:: rtems_shell_login_check
572
573.. code:: c
574
575    bool rtems_shell_login_check(
576    const char \*user,
577    const char \*passphrase
578    );
579
580**DIRECTIVE STATUS CODES:**
581
582``true`` - login is allowed, and
583``false`` - otherwise.
584
585**DESCRIPTION:**
586
587This function checks if the specified passphrase is valid for the specified user.
588
589**NOTES:**
590
591As a side-effect if the specified passphrase is valid for the specified user,
592this function
593
594- performs a filesystem change root operation to the directory of the
595  specified user if the directory path is non-empty,
596
597- changes the owner of the current shell device to the UID of the specified
598  user,
599
600- sets the real and effective UID of the current user environment to the
601  UID of the specified user,
602
603- sets the real and effective GID of the current user environment to the
604  GID of the specified user, and
605
606- sets the supplementary group IDs of the current user environment to the
607  supplementary group IDs of the specified user.
608
609In case the filesystem change root operation fails, then the environment setup
610is aborted and ``false`` is returned.
611
612.. COMMENT: COPYRIGHT (c) 1988-2010.
613
614.. COMMENT: On-Line Applications Research Corporation (OAR).
615
616.. COMMENT: All rights reserved.
617
618General Commands
619################
620
621Introduction
622============
623
624The RTEMS shell has the following general commands:
625
626- ``help`` - Print command help
627
628- ``alias`` - Add alias for an existing command
629
630- ``cmdls`` - List commands
631
632- ``cmdchown`` - Change user or owner of commands
633
634- ``cmdchmod`` - Change mode of commands
635
636- ``date`` - Print or set current date and time
637
638- ``echo`` - Produce message in a shell script
639
640- ``sleep`` - Delay for a specified amount of time
641
642- ``id`` - show uid gid euid and egid
643
644- ``tty`` - show ttyname
645
646- ``whoami`` - print effective user id
647
648- ``getenv`` - print environment variable
649
650- ``setenv`` - set environment variable
651
652- ``unsetenv`` - unset environment variable
653
654- ``time`` - time command execution
655
656- ``logoff`` - logoff from the system
657
658- ``rtc`` - RTC driver configuration
659
660- ``exit`` - alias for logoff command
661
662Commands
663========
664
665This section details the General Commands available.  A
666subsection is dedicated to each of the commands and
667describes the behavior and configuration of that
668command as well as providing an example usage.
669
670help - Print command help
671-------------------------
672.. index:: help
673
674**SYNOPSYS:**
675
676.. code:: c
677
678    help misc
679
680**DESCRIPTION:**
681
682This command prints the command help. Help without arguments prints a
683list of topics and help with a topic prints the help for that topic.
684
685**EXIT STATUS:**
686
687This command returns 0.
688
689**NOTES:**
690
691The help print will break the output up based on the environment
692variable SHELL_LINES. If this environment variable is not set the
693default is 16 lines. If set the number of lines is set to that the
694value. If the shell lines is set 0 there will be no break.
695
696**EXAMPLES:**
697
698The following is an example of how to use ``alias``:
699.. code:: c
700
701    SHLL \[/] $ help
702    help: ('r' repeat last cmd - 'e' edit last cmd)
703    TOPIC? The topics are
704    mem, misc, files, help, rtems, network, monitor
705    SHLL \[/] $ help misc
706    help: list for the topic 'misc'
707    alias        - alias old new
708    time         - time command \[arguments...]
709    joel         - joel \[args] SCRIPT
710    date         - date \[YYYY-MM-DD HH:MM:SS]
711    echo         - echo \[args]
712    sleep        - sleep seconds \[nanoseconds]
713    id           - show uid, gid, euid, and egid
714    tty          - show ttyname
715    whoami       - show current user
716    logoff       - logoff from the system
717    setenv       - setenv \[var] \[string]
718    getenv       - getenv \[var]
719    unsetenv     - unsetenv \[var]
720    umask        - umask \[new_umask]
721    Press any key to continue...
722    rtc          - real time clock read and set
723    SHLL \[/] $ setenv SHELL_ENV 0
724    SHLL \[/] $ help misc
725    help: list for the topic 'misc'
726    alias        - alias old new
727    time         - time command \[arguments...]
728    joel         - joel \[args] SCRIPT
729    date         - date \[YYYY-MM-DD HH:MM:SS]
730    echo         - echo \[args]
731    sleep        - sleep seconds \[nanoseconds]
732    id           - show uid, gid, euid, and egid
733    tty          - show ttyname
734    whoami       - show current user
735    logoff       - logoff from the system
736    setenv       - setenv \[var] \[string]
737    getenv       - getenv \[var]
738    unsetenv     - unsetenv \[var]
739    umask        - umask \[new_umask]
740    rtc          - real time clock read and set
741
742**CONFIGURATION:**
743
744This command has no configuration.
745
746alias - add alias for an existing command
747-----------------------------------------
748.. index:: alias
749
750**SYNOPSYS:**
751
752.. code:: c
753
754    alias oldCommand newCommand
755
756**DESCRIPTION:**
757
758This command adds an alternate name for an existing command to
759the command set.
760
761**EXIT STATUS:**
762
763This command returns 0 on success and non-zero if an error is encountered.
764
765**NOTES:**
766
767NONE
768
769**EXAMPLES:**
770
771The following is an example of how to use ``alias``:
772.. code:: c
773
774    SHLL \[/] $ me
775    shell:me command not found
776    SHLL \[/] $ alias whoami me
777    SHLL \[/] $ me
778    rtems
779    SHLL \[/] $ whoami
780    rtems
781
782**CONFIGURATION:**
783
784.. index:: CONFIGURE_SHELL_NO_COMMAND_ALIAS
785.. index:: CONFIGURE_SHELL_COMMAND_ALIAS
786
787This command is included in the default shell command set.
788When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ALIAS`` to have this
789command included.
790
791This command can be excluded from the shell command set by
792defining ``CONFIGURE_SHELL_NO_COMMAND_ALIAS`` when all
793shell commands have been configured.
794
795**PROGRAMMING INFORMATION:**
796
797.. index:: rtems_shell_rtems_main_alias
798
799The ``alias`` is implemented by a C language function
800which has the following prototype:
801.. code:: c
802
803    int rtems_shell_rtems_main_alias(
804    int    argc,
805    char \**argv
806    );
807
808The configuration structure for the ``alias`` has the
809following prototype:
810.. code:: c
811
812    extern rtems_shell_cmd_t rtems_shell_ALIAS_Command;
813
814cmdls - List commands
815---------------------
816.. index:: cmdls
817
818**SYNOPSYS:**
819
820.. code:: c
821
822    cmdls COMMAND...
823
824**DESCRIPTION:**
825
826This command lists the visible commands of the command set.
827
828**EXIT STATUS:**
829
830This command returns 0 on success and non-zero if an error is encountered.
831
832**NOTES:**
833
834The current user must have read permission to list a command.
835
836**EXAMPLES:**
837
838The following is an example of how to use ``cmdls``:
839.. code:: c
840
841    SHLL \[/] # cmdls help shutdown
842    r-xr-xr-x     0     0 help
843    r-x------     0     0 shutdown
844
845**CONFIGURATION:**
846
847.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDLS
848.. index:: CONFIGURE_SHELL_COMMAND_CMDLS
849
850This command is included in the default shell command set.
851When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDLS`` to have this
852command included.
853
854This command can be excluded from the shell command set by
855defining ``CONFIGURE_SHELL_NO_COMMAND_CMDLS`` when all
856shell commands have been configured.
857
858**PROGRAMMING INFORMATION:**
859
860The configuration structure for the ``cmdls`` has the
861following prototype:
862.. code:: c
863
864    extern rtems_shell_cmd_t rtems_shell_CMDLS_Command;
865
866cmdchown - Change user or owner of commands
867-------------------------------------------
868.. index:: cmdchown
869
870**SYNOPSYS:**
871
872.. code:: c
873
874    cmdchown \[OWNER][:\[GROUP]] COMMAND...
875
876**DESCRIPTION:**
877
878This command changes the user or owner of a command.
879
880**EXIT STATUS:**
881
882This command returns 0 on success and non-zero if an error is encountered.
883
884**NOTES:**
885
886The current user must have an UID of zero or be the command owner to change the
887owner or group.
888
889**EXAMPLES:**
890
891The following is an example of how to use ``cmdchown``:
892.. code:: c
893
894    [/] # cmdls help
895    r-xr-xr-x     0     0 help
896    \[/] # cmdchown 1:1 help
897    \[/] # cmdls help
898    r--r--r--     1     1 help
899
900**CONFIGURATION:**
901
902.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN
903.. index:: CONFIGURE_SHELL_COMMAND_CMDCHOWN
904
905This command is included in the default shell command set.
906When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDCHOWN`` to have this
907command included.
908
909This command can be excluded from the shell command set by
910defining ``CONFIGURE_SHELL_NO_COMMAND_CMDCHOWN`` when all
911shell commands have been configured.
912
913**PROGRAMMING INFORMATION:**
914
915The configuration structure for the ``cmdchown`` has the
916following prototype:
917.. code:: c
918
919    extern rtems_shell_cmd_t rtems_shell_CMDCHOWN_Command;
920
921cmdchmod - Change mode of commands
922----------------------------------
923.. index:: cmdchmod
924
925**SYNOPSYS:**
926
927.. code:: c
928
929    cmdchmod OCTAL-MODE COMMAND...
930
931**DESCRIPTION:**
932
933This command changes the mode of a command.
934
935**EXIT STATUS:**
936
937This command returns 0 on success and non-zero if an error is encountered.
938
939**NOTES:**
940
941The current user must have an UID of zero or be the command owner to change the
942mode.
943
944**EXAMPLES:**
945
946The following is an example of how to use ``cmdchmod``:
947.. code:: c
948
949    [/] # cmdls help
950    r-xr-xr-x     0     0 help
951    \[/] # cmdchmod 544 help
952    \[/] # cmdls help
953    r-xr--r--     0     0 help
954
955**CONFIGURATION:**
956
957.. index:: CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD
958.. index:: CONFIGURE_SHELL_COMMAND_CMDCHMOD
959
960This command is included in the default shell command set.
961When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CMDCHMOD`` to have this
962command included.
963
964This command can be excluded from the shell command set by
965defining ``CONFIGURE_SHELL_NO_COMMAND_CMDCHMOD`` when all
966shell commands have been configured.
967
968**PROGRAMMING INFORMATION:**
969
970The configuration structure for the ``cmdchmod`` has the
971following prototype:
972.. code:: c
973
974    extern rtems_shell_cmd_t rtems_shell_CMDCHMOD_Command;
975
976date - print or set current date and time
977-----------------------------------------
978.. index:: date
979
980**SYNOPSYS:**
981
982.. code:: c
983
984    date
985    date DATE TIME
986
987**DESCRIPTION:**
988
989This command operates one of two modes.  When invoked with no
990arguments, it prints the current date and time.  When invoked
991with both ``date`` and ``time`` arguments, it sets the
992current time.
993
994The ``date`` is specified in ``YYYY-MM-DD`` format.
995The ``time`` is specified in ``HH:MM:SS`` format.
996
997**EXIT STATUS:**
998
999This command returns 0 on success and non-zero if an error is encountered.
1000
1001**NOTES:**
1002
1003This comm
1004
1005**EXAMPLES:**
1006
1007The following is an example of how to use ``date``:
1008.. code:: c
1009
1010    SHLL \[/] $ date
1011    Fri Jan  1 00:00:09 1988
1012    SHLL \[/] $ date 2008-02-29 06:45:32
1013    SHLL \[/] $ date
1014    Fri Feb 29 06:45:35 2008
1015
1016**CONFIGURATION:**
1017
1018.. index:: CONFIGURE_SHELL_NO_COMMAND_DATE
1019.. index:: CONFIGURE_SHELL_COMMAND_DATE
1020
1021This command is included in the default shell command set.
1022When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DATE`` to have this
1023command included.
1024
1025This command can be excluded from the shell command set by
1026defining ``CONFIGURE_SHELL_NO_COMMAND_DATE`` when all
1027shell commands have been configured.
1028
1029**PROGRAMMING INFORMATION:**
1030
1031.. index:: rtems_shell_rtems_main_date
1032
1033The ``date`` is implemented by a C language function
1034which has the following prototype:
1035.. code:: c
1036
1037    int rtems_shell_rtems_main_date(
1038    int    argc,
1039    char \**argv
1040    );
1041
1042The configuration structure for the ``date`` has the
1043following prototype:
1044.. code:: c
1045
1046    extern rtems_shell_cmd_t rtems_shell_DATE_Command;
1047
1048echo - produce message in a shell script
1049----------------------------------------
1050.. index:: echo
1051
1052**SYNOPSYS:**
1053
1054.. code:: c
1055
1056    echo \[-n | -e] args ...
1057
1058**DESCRIPTION:**
1059
1060echo prints its arguments on the standard output, separated by spaces.
1061Unless the *-n* option is present, a newline is output following the
1062arguments.  The *-e* option causes echo to treat the escape sequences
1063specially, as described in the following paragraph.  The *-e* option is the
1064default, and is provided solely for compatibility with other systems.
1065Only one of the options *-n* and *-e* may be given.
1066
1067If any of the following sequences of characters is encountered during
1068output, the sequence is not output.  Instead, the specified action is
1069performed:
1070
1071*\\b*
1072    A backspace character is output.
1073
1074*\\c*
1075    Subsequent output is suppressed.  This is normally used at the
1076    end of the last argument to suppress the trailing newline that
1077    echo would otherwise output.
1078
1079*\\f*
1080    Output a form feed.
1081
1082*\\n*
1083    Output a newline character.
1084
1085*\\r*
1086    Output a carriage return.
1087
1088*\\t*
1089    Output a (horizontal) tab character.
1090
1091*\\v*
1092    Output a vertical tab.
1093
1094*\\0digits*
1095    Output the character whose value is given by zero to three digits.
1096    If there are zero digits, a nul character is output.
1097
1098*\\\\*
1099    Output a backslash.
1100
1101**EXIT STATUS:**
1102
1103This command returns 0 on success and non-zero if an error is encountered.
1104
1105**NOTES:**
1106
1107The octal character escape mechanism (\\0digits) differs from the C lan-
1108guage mechanism.
1109
1110There is no way to force ``echo`` to treat its arguments literally, rather
1111than interpreting them as options and escape sequences.
1112
1113**EXAMPLES:**
1114
1115The following is an example of how to use ``echo``:
1116.. code:: c
1117
1118    SHLL \[/] $ echo a b c
1119    a b c
1120    SHLL \[/] $ echo
1121
1122**CONFIGURATION:**
1123
1124.. index:: CONFIGURE_SHELL_NO_COMMAND_ECHO
1125.. index:: CONFIGURE_SHELL_COMMAND_ECHO
1126
1127This command is included in the default shell command set.
1128When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ECHO`` to have this
1129command included.
1130
1131This command can be excluded from the shell command set by
1132defining ``CONFIGURE_SHELL_NO_COMMAND_ECHO`` when all
1133shell commands have been configured.
1134
1135**PROGRAMMING INFORMATION:**
1136
1137.. index:: rtems_shell_rtems_main_echo
1138
1139The ``echo`` is implemented by a C language function
1140which has the following prototype:
1141.. code:: c
1142
1143    int rtems_shell_rtems_main_echo(
1144    int    argc,
1145    char \**argv
1146    );
1147
1148The configuration structure for the ``echo`` has the
1149following prototype:
1150.. code:: c
1151
1152    extern rtems_shell_cmd_t rtems_shell_ECHO_Command;
1153
1154**ORIGIN:**
1155
1156The implementation and portions of the documentation for this
1157command are from NetBSD 4.0.
1158
1159sleep - delay for a specified amount of time
1160--------------------------------------------
1161.. index:: sleep
1162
1163**SYNOPSYS:**
1164
1165.. code:: c
1166
1167    sleep seconds
1168    sleep seconds nanoseconds
1169
1170**DESCRIPTION:**
1171
1172This command causes the task executing the shell to block
1173for the specified number of ``seconds`` and ``nanoseconds``.
1174
1175**EXIT STATUS:**
1176
1177This command returns 0 on success and non-zero if an error is encountered.
1178
1179**NOTES:**
1180
1181This command is implemented using the ``nanosleep()`` method.
1182
1183The command line interface is similar to the ``sleep`` command
1184found on POSIX systems but the addition of the ``nanoseconds``
1185parameter allows fine grained delays in shell scripts without
1186adding another command such as ``usleep``.
1187
1188**EXAMPLES:**
1189
1190The following is an example of how to use ``sleep``:
1191.. code:: c
1192
1193    SHLL \[/] $ sleep 10
1194    SHLL \[/] $ sleep 0 5000000
1195
1196It is not clear from the above but there is a ten second
1197pause after executing the first command before the prompt
1198is printed.  The second command completes very quickly
1199from a human perspective and there is no noticeable
1200delay in the prompt being printed.
1201
1202**CONFIGURATION:**
1203
1204.. index:: CONFIGURE_SHELL_NO_COMMAND_SLEEP
1205.. index:: CONFIGURE_SHELL_COMMAND_SLEEP
1206
1207This command is included in the default shell command set.
1208When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SLEEP`` to have this
1209command included.
1210
1211This command can be excluded from the shell command set by
1212defining ``CONFIGURE_SHELL_NO_COMMAND_SLEEP`` when all
1213shell commands have been configured.
1214
1215**PROGRAMMING INFORMATION:**
1216
1217.. index:: rtems_shell_rtems_main_sleep
1218
1219The ``sleep`` is implemented by a C language function
1220which has the following prototype:
1221.. code:: c
1222
1223    int rtems_shell_rtems_main_sleep(
1224    int    argc,
1225    char \**argv
1226    );
1227
1228The configuration structure for the ``sleep`` has the
1229following prototype:
1230.. code:: c
1231
1232    extern rtems_shell_cmd_t rtems_shell_SLEEP_Command;
1233
1234id - show uid gid euid and egid
1235-------------------------------
1236.. index:: id
1237
1238**SYNOPSYS:**
1239
1240.. code:: c
1241
1242    id
1243
1244**DESCRIPTION:**
1245
1246This command prints the user identity.  This includes the user id
1247(uid), group id (gid), effective user id (euid), and effective
1248group id (egid).
1249
1250**EXIT STATUS:**
1251
1252This command returns 0 on success and non-zero if an error is encountered.
1253
1254**NOTES:**
1255
1256Remember there is only one POSIX process in a single processor RTEMS
1257application. Each thread may have its own user identity and that
1258identity is used by the filesystem to enforce permissions.
1259
1260**EXAMPLES:**
1261
1262The first example of the ``id`` command is from a session logged
1263in as the normal user ``rtems``:
1264.. code:: c
1265
1266    SHLL \[/] # id
1267    uid=1(rtems),gid=1(rtems),euid=1(rtems),egid=1(rtems)
1268
1269The second example of the ``id`` command is from a session logged
1270in as the ``root`` user:
1271.. code:: c
1272
1273    SHLL \[/] # id
1274    uid=0(root),gid=0(root),euid=0(root),egid=0(root)
1275
1276**CONFIGURATION:**
1277
1278.. index:: CONFIGURE_SHELL_NO_COMMAND_ID
1279.. index:: CONFIGURE_SHELL_COMMAND_ID
1280
1281This command is included in the default shell command set.
1282When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ID`` to have this
1283command included.
1284
1285This command can be excluded from the shell command set by
1286defining ``CONFIGURE_SHELL_NO_COMMAND_ID`` when all
1287shell commands have been configured.
1288
1289**PROGRAMMING INFORMATION:**
1290
1291.. index:: rtems_shell_rtems_main_id
1292
1293The ``id`` is implemented by a C language function
1294which has the following prototype:
1295.. code:: c
1296
1297    int rtems_shell_rtems_main_id(
1298    int    argc,
1299    char \**argv
1300    );
1301
1302The configuration structure for the ``id`` has the
1303following prototype:
1304.. code:: c
1305
1306    extern rtems_shell_cmd_t rtems_shell_ID_Command;
1307
1308tty - show ttyname
1309------------------
1310.. index:: tty
1311
1312**SYNOPSYS:**
1313
1314.. code:: c
1315
1316    tty
1317
1318**DESCRIPTION:**
1319
1320This command prints the file name of the device connected
1321to standard input.
1322
1323**EXIT STATUS:**
1324
1325This command returns 0 on success and non-zero if an error is encountered.
1326
1327**NOTES:**
1328
1329NONE
1330
1331**EXAMPLES:**
1332
1333The following is an example of how to use ``tty``:
1334.. code:: c
1335
1336    SHLL \[/] $ tty
1337    /dev/console
1338
1339**CONFIGURATION:**
1340
1341.. index:: CONFIGURE_SHELL_NO_COMMAND_TTY
1342.. index:: CONFIGURE_SHELL_COMMAND_TTY
1343
1344This command is included in the default shell command set.
1345When building a custom command set, define``CONFIGURE_SHELL_COMMAND_TTY`` to have this
1346command included.
1347
1348This command can be excluded from the shell command set by
1349defining ``CONFIGURE_SHELL_NO_COMMAND_TTY`` when all
1350shell commands have been configured.
1351
1352**PROGRAMMING INFORMATION:**
1353
1354.. index:: rtems_shell_rtems_main_tty
1355
1356The ``tty`` is implemented by a C language function
1357which has the following prototype:
1358.. code:: c
1359
1360    int rtems_shell_rtems_main_tty(
1361    int    argc,
1362    char \**argv
1363    );
1364
1365The configuration structure for the ``tty`` has the
1366following prototype:
1367.. code:: c
1368
1369    extern rtems_shell_cmd_t rtems_shell_TTY_Command;
1370
1371whoami - print effective user id
1372--------------------------------
1373.. index:: whoami
1374
1375**SYNOPSYS:**
1376
1377.. code:: c
1378
1379    whoami
1380
1381**DESCRIPTION:**
1382
1383This command displays the user name associated with the current
1384effective user id.
1385
1386**EXIT STATUS:**
1387
1388This command always succeeds.
1389
1390**NOTES:**
1391
1392NONE
1393
1394**EXAMPLES:**
1395
1396The following is an example of how to use ``whoami``:
1397.. code:: c
1398
1399    SHLL \[/] $ whoami
1400    rtems
1401
1402**CONFIGURATION:**
1403
1404.. index:: CONFIGURE_SHELL_NO_COMMAND_WHOAMI
1405.. index:: CONFIGURE_SHELL_COMMAND_WHOAMI
1406
1407This command is included in the default shell command set.
1408When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WHOAMI`` to have this
1409command included.
1410
1411This command can be excluded from the shell command set by
1412defining ``CONFIGURE_SHELL_NO_COMMAND_WHOAMI`` when all
1413shell commands have been configured.
1414
1415**PROGRAMMING INFORMATION:**
1416
1417.. index:: rtems_shell_rtems_main_whoami
1418
1419The ``whoami`` is implemented by a C language function
1420which has the following prototype:
1421.. code:: c
1422
1423    int rtems_shell_rtems_main_whoami(
1424    int    argc,
1425    char \**argv
1426    );
1427
1428The configuration structure for the ``whoami`` has the
1429following prototype:
1430.. code:: c
1431
1432    extern rtems_shell_cmd_t rtems_shell_WHOAMI_Command;
1433
1434getenv - print environment variable
1435-----------------------------------
1436.. index:: getenv
1437
1438**SYNOPSYS:**
1439
1440.. code:: c
1441
1442    getenv variable
1443
1444**DESCRIPTION:**
1445
1446This command is used to display the value of a ``variable`` in the set
1447of environment variables.
1448
1449**EXIT STATUS:**
1450
1451This command will return 1 and print a diagnostic message if
1452a failure occurs.
1453
1454**NOTES:**
1455
1456The entire RTEMS application shares a single set of environment variables.
1457
1458**EXAMPLES:**
1459
1460The following is an example of how to use ``getenv``:
1461.. code:: c
1462
1463    SHLL \[/] $ getenv BASEPATH
1464    /mnt/hda1
1465
1466**CONFIGURATION:**
1467
1468.. index:: CONFIGURE_SHELL_NO_COMMAND_GETENV
1469.. index:: CONFIGURE_SHELL_COMMAND_GETENV
1470
1471This command is included in the default shell command set.
1472When building a custom command set, define``CONFIGURE_SHELL_COMMAND_GETENV`` to have this
1473command included.
1474
1475This command can be excluded from the shell command set by
1476defining ``CONFIGURE_SHELL_NO_COMMAND_GETENV`` when all
1477shell commands have been configured.
1478
1479**PROGRAMMING INFORMATION:**
1480
1481.. index:: rtems_shell_rtems_main_getenv
1482
1483The ``getenv`` is implemented by a C language function
1484which has the following prototype:
1485.. code:: c
1486
1487    int rtems_shell_rtems_main_getenv(
1488    int    argc,
1489    char \**argv
1490    );
1491
1492The configuration structure for the ``getenv`` has the
1493following prototype:
1494.. code:: c
1495
1496    extern rtems_shell_cmd_t rtems_shell_GETENV_Command;
1497
1498setenv - set environment variable
1499---------------------------------
1500.. index:: setenv
1501
1502**SYNOPSYS:**
1503
1504.. code:: c
1505
1506    setenv variable \[value]
1507
1508**DESCRIPTION:**
1509
1510This command is used to add a new ``variable`` to the set of environment
1511variables or to modify the variable of an already existing ``variable``.
1512If the ``value`` is not provided, the ``variable`` will be set to the
1513empty string.
1514
1515**EXIT STATUS:**
1516
1517This command will return 1 and print a diagnostic message if
1518a failure occurs.
1519
1520**NOTES:**
1521
1522The entire RTEMS application shares a single set of environment variables.
1523
1524**EXAMPLES:**
1525
1526The following is an example of how to use ``setenv``:
1527.. code:: c
1528
1529    SHLL \[/] $ setenv BASEPATH /mnt/hda1
1530
1531**CONFIGURATION:**
1532
1533.. index:: CONFIGURE_SHELL_NO_COMMAND_SETENV
1534.. index:: CONFIGURE_SHELL_COMMAND_SETENV
1535
1536This command is included in the default shell command set.
1537When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SETENV`` to have this
1538command included.
1539
1540This command can be excluded from the shell command set by
1541defining ``CONFIGURE_SHELL_NO_COMMAND_SETENV`` when all
1542shell commands have been configured.
1543
1544**PROGRAMMING INFORMATION:**
1545
1546.. index:: rtems_shell_rtems_main_setenv
1547
1548The ``setenv`` is implemented by a C language function
1549which has the following prototype:
1550.. code:: c
1551
1552    int rtems_shell_rtems_main_setenv(
1553    int    argc,
1554    char \**argv
1555    );
1556
1557The configuration structure for the ``setenv`` has the
1558following prototype:
1559.. code:: c
1560
1561    extern rtems_shell_cmd_t rtems_shell_SETENV_Command;
1562
1563unsetenv - unset environment variable
1564-------------------------------------
1565.. index:: unsetenv
1566
1567**SYNOPSYS:**
1568
1569.. code:: c
1570
1571    unsetenv variable
1572
1573**DESCRIPTION:**
1574
1575This command is remove to a ``variable`` from the set of environment
1576variables.
1577
1578**EXIT STATUS:**
1579
1580This command will return 1 and print a diagnostic message if
1581a failure occurs.
1582
1583**NOTES:**
1584
1585The entire RTEMS application shares a single set of environment variables.
1586
1587**EXAMPLES:**
1588
1589The following is an example of how to use ``unsetenv``:
1590.. code:: c
1591
1592    SHLL \[/] $ unsetenv BASEPATH
1593
1594**CONFIGURATION:**
1595
1596.. index:: CONFIGURE_SHELL_NO_COMMAND_UNSETENV
1597.. index:: CONFIGURE_SHELL_COMMAND_UNSETENV
1598
1599This command is included in the default shell command set.
1600When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UNSETENV`` to have this
1601command included.
1602
1603This command can be excluded from the shell command set by
1604defining ``CONFIGURE_SHELL_NO_COMMAND_UNSETENV`` when all
1605shell commands have been configured.
1606
1607**PROGRAMMING INFORMATION:**
1608
1609.. index:: rtems_shell_rtems_main_unsetenv
1610
1611The ``unsetenv`` is implemented by a C language function
1612which has the following prototype:
1613.. code:: c
1614
1615    int rtems_shell_rtems_main_unsetenv(
1616    int    argc,
1617    char \**argv
1618    );
1619
1620The configuration structure for the ``unsetenv`` has the
1621following prototype:
1622.. code:: c
1623
1624    extern rtems_shell_cmd_t rtems_shell_UNSETENV_Command;
1625
1626time - time command execution
1627-----------------------------
1628.. index:: time
1629
1630**SYNOPSYS:**
1631
1632.. code:: c
1633
1634    time command \[argument ...]
1635
1636**DESCRIPTION:**
1637
1638The time command executes and times a command.  After the command
1639finishes, time writes the total time elapsed.  Times are reported in
1640seconds.
1641
1642**EXIT STATUS:**
1643
1644This command returns 0 on success and non-zero if an error is encountered.
1645
1646**NOTES:**
1647
1648None.
1649
1650**EXAMPLES:**
1651
1652The following is an example of how to use ``time``:
1653.. code:: c
1654
1655    SHLL \[/] $ time cp -r /nfs/directory /c
1656
1657**CONFIGURATION:**
1658
1659.. index:: CONFIGURE_SHELL_NO_COMMAND_TIME
1660.. index:: CONFIGURE_SHELL_COMMAND_TIME
1661
1662This command is included in the default shell command set.  When
1663building a custom command set, define``CONFIGURE_SHELL_COMMAND_TIME`` to have this command included.
1664
1665This command can be excluded from the shell command set by
1666defining ``CONFIGURE_SHELL_NO_COMMAND_TIME`` when all
1667shell commands have been configured.
1668
1669**PROGRAMMING INFORMATION:**
1670
1671.. index:: rtems_shell_rtems_main_time
1672
1673The ``time`` is implemented by a C language function
1674which has the following prototype:
1675.. code:: c
1676
1677    int rtems_shell_rtems_main_time(
1678    int    argc,
1679    char \**argv
1680    );
1681
1682The configuration structure for the ``time`` has the
1683following prototype:
1684.. code:: c
1685
1686    extern rtems_shell_cmd_t rtems_shell_TIME_Command;
1687
1688.. _General-Commands-logoff-_002d-logoff-from-the-system:
1689
1690logoff - logoff from the system
1691-------------------------------
1692.. index:: logoff
1693
1694**SYNOPSYS:**
1695
1696.. code:: c
1697
1698    logoff
1699
1700**DESCRIPTION:**
1701
1702This command logs the user out of the shell.
1703
1704**EXIT STATUS:**
1705
1706This command does not return.
1707
1708**NOTES:**
1709
1710The system behavior when the shell is exited depends upon how the
1711shell was initiated.  The typical behavior is that a login prompt
1712will be displayed for the next login attempt or that the connection
1713will be dropped by the RTEMS system.
1714
1715**EXAMPLES:**
1716
1717The following is an example of how to use ``logoff``:
1718.. code:: c
1719
1720    SHLL \[/] $ logoff
1721    logoff from the system...
1722
1723**CONFIGURATION:**
1724
1725.. index:: CONFIGURE_SHELL_NO_COMMAND_LOGOFF
1726.. index:: CONFIGURE_SHELL_COMMAND_LOGOFF
1727
1728This command is included in the default shell command set.
1729When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LOGOFF`` to have this
1730command included.
1731
1732This command can be excluded from the shell command set by
1733defining ``CONFIGURE_SHELL_NO_COMMAND_LOGOFF`` when all
1734shell commands have been configured.
1735
1736**PROGRAMMING INFORMATION:**
1737
1738.. index:: rtems_shell_rtems_main_logoff
1739
1740The ``logoff`` is implemented by a C language function
1741which has the following prototype:
1742.. code:: c
1743
1744    int rtems_shell_rtems_main_logoff(
1745    int    argc,
1746    char \**argv
1747    );
1748
1749The configuration structure for the ``logoff`` has the
1750following prototype:
1751.. code:: c
1752
1753    extern rtems_shell_cmd_t rtems_shell_LOGOFF_Command;
1754
1755rtc - RTC driver configuration
1756------------------------------
1757.. index:: rtc
1758
1759**SYNOPSYS:**
1760
1761.. code:: c
1762
1763    rtc
1764
1765**CONFIGURATION:**
1766
1767.. index:: CONFIGURE_SHELL_NO_COMMAND_RTC
1768.. index:: CONFIGURE_SHELL_COMMAND_RTC
1769
1770This command is included in the default shell command set.
1771When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RTC`` to have this
1772command included.
1773
1774This command can be excluded from the shell command set by
1775defining ``CONFIGURE_SHELL_NO_COMMAND_RTC`` when all
1776shell commands have been configured.
1777
1778exit - exit the shell
1779---------------------
1780.. index:: exit
1781
1782**SYNOPSYS:**
1783
1784.. code:: c
1785
1786    exit
1787
1788**DESCRIPTION:**
1789
1790This command causes the shell interpreter to ``exit``.
1791
1792**EXIT STATUS:**
1793
1794This command does not return.
1795
1796**NOTES:**
1797
1798In contrast to :ref:`logoff <General-Commands-logoff-_002d-logoff-from-the-system>`,
1799this command is built into the shell interpreter loop.
1800
1801**EXAMPLES:**
1802
1803The following is an example of how to use ``exit``:
1804.. code:: c
1805
1806    SHLL \[/] $ exit
1807    Shell exiting
1808
1809**CONFIGURATION:**
1810
1811This command is always present and cannot be disabled.
1812
1813**PROGRAMMING INFORMATION:**
1814
1815The ``exit`` is implemented directly in the shell interpreter.
1816There is no C routine associated with it.
1817
1818.. COMMENT: COPYRIGHT (c) 1988-2008.
1819
1820.. COMMENT: On-Line Applications Research Corporation (OAR).
1821
1822.. COMMENT: All rights reserved.
1823
1824File and Directory Commands
1825###########################
1826
1827Introduction
1828============
1829
1830The RTEMS shell has the following file and directory commands:
1831
1832- ``blksync`` - sync the block driver
1833
1834- ``cat`` - display file contents
1835
1836- ``cd`` - alias for chdir
1837
1838- ``chdir`` - change the current directory
1839
1840- ``chmod`` - change permissions of a file
1841
1842- ``chroot`` - change the root directory
1843
1844- ``cp`` - copy files
1845
1846- ``dd`` - format disks
1847
1848- ``debugrfs`` - debug RFS file system
1849
1850- ``df`` - display file system disk space usage
1851
1852- ``dir`` - alias for ls
1853
1854- ``fdisk`` - format disks
1855
1856- ``hexdump`` - format disks
1857
1858- ``ln`` - make links
1859
1860- ``ls`` - list files in the directory
1861
1862- ``md5`` - display file system disk space usage
1863
1864- ``mkdir`` - create a directory
1865
1866- ``mkdos`` - DOSFS disk format
1867
1868- ``mknod`` - make device special file
1869
1870- ``mkrfs`` - format RFS file system
1871
1872- ``mount`` - mount disk
1873
1874- ``mv`` - move files
1875
1876- ``pwd`` - print work directory
1877
1878- ``rmdir`` - remove empty directories
1879
1880- ``rm`` - remove files
1881
1882- ``umask`` - Set file mode creation mask
1883
1884- ``unmount`` - unmount disk
1885
1886Commands
1887========
1888
1889This section details the File and Directory Commands available.  A
1890subsection is dedicated to each of the commands and
1891describes the behavior and configuration of that
1892command as well as providing an example usage.
1893
1894blksync - sync the block driver
1895-------------------------------
1896.. index:: blksync
1897
1898**SYNOPSYS:**
1899
1900.. code:: c
1901
1902    blksync driver
1903
1904**DESCRIPTION:**
1905
1906This command XXX
1907
1908**EXIT STATUS:**
1909
1910This command returns 0 on success and non-zero if an error is encountered.
1911
1912**NOTES:**
1913
1914NONE
1915
1916**EXAMPLES:**
1917
1918The following is an example of how to use ``blksync``:
1919.. code:: c
1920
1921    EXAMPLE_TBD
1922
1923**CONFIGURATION:**
1924
1925.. index:: CONFIGURE_SHELL_NO_COMMAND_BLKSYNC
1926.. index:: CONFIGURE_SHELL_COMMAND_BLKSYNC
1927
1928This command is included in the default shell command set.
1929When building a custom command set, define``CONFIGURE_SHELL_COMMAND_BLKSYNC`` to have this
1930command included.
1931
1932This command can be excluded from the shell command set by
1933defining ``CONFIGURE_SHELL_NO_COMMAND_BLKSYNC`` when all
1934shell commands have been configured.
1935
1936**PROGRAMMING INFORMATION:**
1937
1938.. index:: rtems_shell_rtems_main_blksync
1939
1940The ``blksync`` is implemented by a C language function
1941which has the following prototype:
1942.. code:: c
1943
1944    int rtems_shell_rtems_main_blksync(
1945    int    argc,
1946    char \**argv
1947    );
1948
1949The configuration structure for the ``blksync`` has the
1950following prototype:
1951.. code:: c
1952
1953    extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command;
1954
1955cat - display file contents
1956---------------------------
1957.. index:: cat
1958
1959**SYNOPSYS:**
1960
1961.. code:: c
1962
1963    cat file1 \[file2 .. fileN]
1964
1965**DESCRIPTION:**
1966
1967This command displays the contents of the specified files.
1968
1969**EXIT STATUS:**
1970
1971This command returns 0 on success and non-zero if an error is encountered.
1972
1973**NOTES:**
1974
1975It is possible to read the input from a device file using ``cat``.
1976
1977**EXAMPLES:**
1978
1979The following is an example of how to use ``cat``:
1980.. code:: c
1981
1982    SHLL \[/] # cat /etc/passwd
1983    root:\*:0:0:root::/:/bin/sh
1984    rtems:\*:1:1:RTEMS Application::/:/bin/sh
1985    tty:!:2:2:tty owner::/:/bin/false
1986
1987**CONFIGURATION:**
1988
1989.. index:: CONFIGURE_SHELL_NO_COMMAND_CAT
1990.. index:: CONFIGURE_SHELL_COMMAND_CAT
1991
1992This command is included in the default shell command set.
1993When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CAT`` to have this
1994command included.
1995
1996This command can be excluded from the shell command set by
1997defining ``CONFIGURE_SHELL_NO_COMMAND_CAT`` when all
1998shell commands have been configured.
1999
2000**PROGRAMMING INFORMATION:**
2001
2002.. index:: rtems_shell_rtems_main_cat
2003
2004The ``cat`` is implemented by a C language function
2005which has the following prototype:
2006.. code:: c
2007
2008    int rtems_shell_rtems_main_cat(
2009    int    argc,
2010    char \**argv
2011    );
2012
2013The configuration structure for the ``cat`` has the
2014following prototype:
2015.. code:: c
2016
2017    extern rtems_shell_cmd_t rtems_shell_CAT_Command;
2018
2019cd - alias for chdir
2020--------------------
2021.. index:: cd
2022
2023**SYNOPSYS:**
2024
2025.. code:: c
2026
2027    cd directory
2028
2029**DESCRIPTION:**
2030
2031This command is an alias or alternate name for the ``chdir``.
2032See :ref:`cd <File-and-Directory-Commands-chdir-_002d-change-the-current-directory>`
2033for more information.
2034
2035**EXIT STATUS:**
2036
2037This command returns 0 on success and non-zero if an error is encountered.
2038
2039**NOTES:**
2040
2041NONE
2042
2043**EXAMPLES:**
2044
2045The following is an example of how to use ``cd``:
2046.. code:: c
2047
2048    SHLL \[/] $ cd etc
2049    SHLL \[/etc] $ cd /
2050    SHLL \[/] $ cd /etc
2051    SHLL \[/etc] $ pwd
2052    /etc
2053    SHLL \[/etc] $ cd /
2054    SHLL \[/] $ pwd
2055    /
2056    SHLL \[/] $ cd etc
2057    SHLL \[/etc] $ cd ..
2058    SHLL \[/] $ pwd
2059    /
2060
2061**CONFIGURATION:**
2062
2063.. index:: CONFIGURE_SHELL_NO_COMMAND_CD
2064.. index:: CONFIGURE_SHELL_COMMAND_CD
2065
2066This command is included in the default shell command set.
2067When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CD`` to have this
2068command included.
2069
2070This command can be excluded from the shell command set by
2071defining ``CONFIGURE_SHELL_NO_COMMAND_CD`` when all
2072shell commands have been configured.
2073
2074**PROGRAMMING INFORMATION:**
2075
2076.. index:: rtems_shell_rtems_main_cd
2077
2078The ``cd`` is implemented by a C language function
2079which has the following prototype:
2080.. code:: c
2081
2082    int rtems_shell_rtems_main_cd(
2083    int    argc,
2084    char \**argv
2085    );
2086
2087The configuration structure for the ``cd`` has the
2088following prototype:
2089.. code:: c
2090
2091    extern rtems_shell_cmd_t rtems_shell_CD_Command;
2092
2093.. _File-and-Directory-Commands-chdir-_002d-change-the-current-directory:
2094
2095chdir - change the current directory
2096------------------------------------
2097.. index:: chdir
2098
2099**SYNOPSYS:**
2100
2101.. code:: c
2102
2103    chdir \[dir]
2104
2105**DESCRIPTION:**
2106
2107This command is used to change the current working directory to
2108the specified directory.  If no arguments are given, the current
2109working directory will be changed to ``/``.
2110
2111**EXIT STATUS:**
2112
2113This command returns 0 on success and non-zero if an error is encountered.
2114
2115**NOTES:**
2116
2117NONE
2118
2119**EXAMPLES:**
2120
2121The following is an example of how to use ``chdir``:
2122.. code:: c
2123
2124    SHLL \[/] $ pwd
2125    /
2126    SHLL \[/] $ chdir etc
2127    SHLL \[/etc] $ pwd
2128    /etc
2129
2130**CONFIGURATION:**
2131
2132.. index:: CONFIGURE_SHELL_NO_COMMAND_CHDIR
2133.. index:: CONFIGURE_SHELL_COMMAND_CHDIR
2134
2135This command is included in the default shell command set.
2136When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHDIR`` to have this
2137command included.
2138
2139This command can be excluded from the shell command set by
2140defining ``CONFIGURE_SHELL_NO_COMMAND_CHDIR`` when all
2141shell commands have been configured.
2142
2143**PROGRAMMING INFORMATION:**
2144
2145.. index:: rtems_shell_rtems_main_chdir
2146
2147The ``chdir`` is implemented by a C language function
2148which has the following prototype:
2149.. code:: c
2150
2151    int rtems_shell_rtems_main_chdir(
2152    int    argc,
2153    char \**argv
2154    );
2155
2156The configuration structure for the ``chdir`` has the
2157following prototype:
2158.. code:: c
2159
2160    extern rtems_shell_cmd_t rtems_shell_CHDIR_Command;
2161
2162chmod - change permissions of a file
2163------------------------------------
2164.. index:: chmod
2165
2166**SYNOPSYS:**
2167
2168.. code:: c
2169
2170    chmod permissions file1 \[file2...]
2171
2172**DESCRIPTION:**
2173
2174This command changes the permissions on the files specified to the
2175indicated ``permissions``.  The permission values are POSIX based
2176with owner, group, and world having individual read, write, and
2177executive permission bits.
2178
2179**EXIT STATUS:**
2180
2181This command returns 0 on success and non-zero if an error is encountered.
2182
2183**NOTES:**
2184
2185The ``chmod`` command only takes numeric representations of
2186the permissions.
2187
2188**EXAMPLES:**
2189
2190The following is an example of how to use ``chmod``:
2191.. code:: c
2192
2193    SHLL \[/] # cd etc
2194    SHLL \[/etc] # ls
2195    -rw-r--r--   1   root   root         102 Jan 01 00:00 passwd
2196    -rw-r--r--   1   root   root          42 Jan 01 00:00 group
2197    -rw-r--r--   1   root   root          30 Jan 01 00:00 issue
2198    -rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net
2199    4 files 202 bytes occupied
2200    SHLL \[/etc] # chmod 0777 passwd
2201    SHLL \[/etc] # ls
2202    -rwxrwxrwx   1   root   root         102 Jan 01 00:00 passwd
2203    -rw-r--r--   1   root   root          42 Jan 01 00:00 group
2204    -rw-r--r--   1   root   root          30 Jan 01 00:00 issue
2205    -rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net
2206    4 files 202 bytes occupied
2207    SHLL \[/etc] # chmod 0322 passwd
2208    SHLL \[/etc] # ls
2209    --wx-w--w-   1 nouser   root         102 Jan 01 00:00 passwd
2210    -rw-r--r--   1 nouser   root          42 Jan 01 00:00 group
2211    -rw-r--r--   1 nouser   root          30 Jan 01 00:00 issue
2212    -rw-r--r--   1 nouser   root          28 Jan 01 00:00 issue.net
2213    4 files 202 bytes occupied
2214    SHLL \[/etc] # chmod 0644 passwd
2215    SHLL \[/etc] # ls
2216    -rw-r--r--   1   root   root         102 Jan 01 00:00 passwd
2217    -rw-r--r--   1   root   root          42 Jan 01 00:00 group
2218    -rw-r--r--   1   root   root          30 Jan 01 00:00 issue
2219    -rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net
2220    4 files 202 bytes occupied
2221
2222**CONFIGURATION:**
2223
2224.. index:: CONFIGURE_SHELL_NO_COMMAND_CHMOD
2225.. index:: CONFIGURE_SHELL_COMMAND_CHMOD
2226
2227This command is included in the default shell command set.
2228When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHMOD`` to have this
2229command included.
2230
2231This command can be excluded from the shell command set by
2232defining ``CONFIGURE_SHELL_NO_COMMAND_CHMOD`` when all
2233shell commands have been configured.
2234
2235**PROGRAMMING INFORMATION:**
2236
2237.. index:: rtems_shell_rtems_main_chmod
2238
2239The ``chmod`` is implemented by a C language function
2240which has the following prototype:
2241.. code:: c
2242
2243    int rtems_shell_rtems_main_chmod(
2244    int    argc,
2245    char \**argv
2246    );
2247
2248The configuration structure for the ``chmod`` has the
2249following prototype:
2250.. code:: c
2251
2252    extern rtems_shell_cmd_t rtems_shell_CHMOD_Command;
2253
2254chroot - change the root directory
2255----------------------------------
2256.. index:: chroot
2257
2258**SYNOPSYS:**
2259
2260.. code:: c
2261
2262    chroot \[dir]
2263
2264**DESCRIPTION:**
2265
2266This command changes the root directory to ``dir`` for subsequent
2267commands.
2268
2269**EXIT STATUS:**
2270
2271This command returns 0 on success and non-zero if an error is encountered.
2272
2273The destination directory ``dir`` must exist.
2274
2275**NOTES:**
2276
2277NONE
2278
2279**EXAMPLES:**
2280
2281The following is an example of how to use ``chroot``
2282and the impact it has on the environment for subsequent
2283command invocations:
2284.. code:: c
2285
2286    SHLL \[/] $ cat passwd
2287    cat: passwd: No such file or directory
2288    SHLL \[/] $ chroot etc
2289    SHLL \[/] $ cat passwd
2290    root:\*:0:0:root::/:/bin/sh
2291    rtems:\*:1:1:RTEMS Application::/:/bin/sh
2292    tty:!:2:2:tty owner::/:/bin/false
2293    SHLL \[/] $ cat /etc/passwd
2294    cat: /etc/passwd: No such file or directory
2295
2296**CONFIGURATION:**
2297
2298.. index:: CONFIGURE_SHELL_NO_COMMAND_CHROOT
2299.. index:: CONFIGURE_SHELL_COMMAND_CHROOT
2300
2301This command is included in the default shell command set.
2302When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CHROOT`` to have this
2303command included. Additional to that you have to add one
2304POSIX key value pair for each thread where you want to use
2305the command.
2306
2307This command can be excluded from the shell command set by
2308defining ``CONFIGURE_SHELL_NO_COMMAND_CHROOT`` when all
2309shell commands have been configured.
2310
2311**PROGRAMMING INFORMATION:**
2312
2313.. index:: rtems_shell_rtems_main_chroot
2314
2315The ``chroot`` is implemented by a C language function
2316which has the following prototype:
2317.. code:: c
2318
2319    int rtems_shell_rtems_main_chroot(
2320    int    argc,
2321    char \**argv
2322    );
2323
2324The configuration structure for the ``chroot`` has the
2325following prototype:
2326.. code:: c
2327
2328    extern rtems_shell_cmd_t rtems_shell_CHROOT_Command;
2329
2330cp - copy files
2331---------------
2332.. index:: cp
2333
2334**SYNOPSYS:**
2335
2336.. code:: c
2337
2338    cp \[-R \[-H | -L | -P]] \[-f | -i] \[-pv] src target
2339    cp \[-R \[-H | -L] ] \[-f | -i] \[-NpPv] source_file ... target_directory
2340
2341**DESCRIPTION:**
2342
2343In the first synopsis form, the cp utility copies the contents of the
2344source_file to the target_file. In the second synopsis form, the contents of
2345each named source_file is copied to the destination target_directory. The names
2346of the files themselves are not changed. If cp detects an attempt to copy a
2347file to itself, the copy will fail.
2348
2349The following options are available:
2350
2351*-f*
2352    For each existing destination pathname, attempt to overwrite it. If permissions
2353    do not allow copy to succeed, remove it and create a new file, without
2354    prompting for confirmation. (The -i option is ignored if the -f option is
2355    specified.)
2356
2357*-H*
2358    If the -R option is specified, symbolic links on the command line are followed.
2359    (Symbolic links encountered in the tree traversal are not followed.)
2360
2361*-i*
2362    Causes cp to write a prompt to the standard error output before copying a file
2363    that would overwrite an existing file. If the response from the standard input
2364    begins with the character ’y’, the file copy is attempted.
2365
2366*-L*
2367    If the -R option is specified, all symbolic links are followed.
2368
2369*-N*
2370    When used with -p, do not copy file flags.
2371
2372*-P*
2373    No symbolic links are followed.
2374
2375*-p*
2376    Causes cp to preserve in the copy as many of the modification time, access
2377    time, file flags, file mode, user ID, and group ID as allowed by permissions.
2378    If the user ID and group ID cannot be preserved, no error message is displayed
2379    and the exit value is not altered.
2380    If the source file has its set user ID bit on and the user ID cannot be
2381    preserved, the set user ID bit is not preserved in the copy’s permissions. If
2382    the source file has its set group ID bit on and the group ID cannot be
2383    preserved, the set group ID bit is not preserved in the copy’s permissions. If
2384    the source file has both its set user ID and set group ID bits on, and either
2385    the user ID or group ID cannot be preserved, neither the set user ID or set
2386    group ID bits are preserved in the copy’s permissions.
2387
2388*-R*
2389    If source_file designates a directory, cp copies the directory and the entire
2390    subtree connected at that point. This option also causes symbolic links to be
2391    copied, rather than indirected through, and for cp to create special files
2392    rather than copying them as normal files. Created directories have the same
2393    mode as the corresponding source directory, unmodified by the process’s umask.
2394
2395*-v*
2396    Cause cp to be verbose, showing files as they are copied.
2397
2398For each destination file that already exists, its contents are overwritten if
2399permissions allow, but its mode, user ID, and group ID are unchanged.
2400
2401In the second synopsis form, target_directory must exist unless there is only
2402one named source_file which is a directory and the -R flag is specified.
2403
2404If the destination file does not exist, the mode of the source file is used as
2405modified by the file mode creation mask (umask, see csh(1)). If the source file
2406has its set user ID bit on, that bit is removed unless both the source file and
2407the destination file are owned by the same user. If the source file has its set
2408group ID bit on, that bit is removed unless both the source file and the
2409destination file are in the same group and the user is a member of that group.
2410If both the set user ID and set group ID bits are set, all of the above
2411conditions must be fulfilled or both bits are removed.
2412
2413Appropriate permissions are required for file creation or overwriting.
2414
2415Symbolic links are always followed unless the -R flag is set, in which case
2416symbolic links are not followed, by default. The -H or -L flags (in conjunction
2417with the -R flag), as well as the -P flag cause symbolic links to be followed
2418as described above. The -H and -L options are ignored unless the -R option is
2419specified. In addition, these options override eachsubhedading other and the
2420command’s actions are determined by the last one specified.
2421
2422**EXIT STATUS:**
2423
2424This command returns 0 on success and non-zero if an error is encountered.
2425
2426**NOTES:**
2427
2428NONE
2429
2430**EXAMPLES:**
2431
2432The following is an example of how to use ``cp`` to
2433copy a file to a new name in the current directory:
2434.. code:: c
2435
2436    SHLL \[/] # cat joel
2437    cat: joel: No such file or directory
2438    SHLL \[/] # cp etc/passwd joel
2439    SHLL \[/] # cat joel
2440    root:\*:0:0:root::/:/bin/sh
2441    rtems:\*:1:1:RTEMS Application::/:/bin/sh
2442    tty:!:2:2:tty owner::/:/bin/false
2443    SHLL \[/] # ls
2444    drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
2445    drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
2446    -rw-r--r--   1   root   root         102 Jan 01 00:00 joel
2447    3 files 1710 bytes occupied
2448
2449The following is an example of how to use ``cp`` to
2450copy one or more files to a destination directory and
2451use the same ``basename`` in the destination directory:
2452.. code:: c
2453
2454    SHLL \[/] # mkdir tmp
2455    SHLL \[/] # ls tmp
2456    0 files 0 bytes occupied
2457    SHLL \[/] # cp /etc/passwd tmp
2458    SHLL \[/] # ls /tmp
2459    -rw-r--r--   1   root   root         102 Jan 01 00:01 passwd
2460    1 files 102 bytes occupied
2461    SHLL \[/] # cp /etc/passwd /etc/group /tmp
2462    SHLL \[/] # ls /tmp
2463    -rw-r--r--   1   root   root         102 Jan 01 00:01 passwd
2464    -rw-r--r--   1   root   root          42 Jan 01 00:01 group
2465    2 files 144 bytes occupied
2466    SHLL \[/] #
2467
2468**CONFIGURATION:**
2469
2470.. index:: CONFIGURE_SHELL_NO_COMMAND_CP
2471.. index:: CONFIGURE_SHELL_COMMAND_CP
2472
2473This command is included in the default shell command set.
2474When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CP`` to have this
2475command included.
2476
2477This command can be excluded from the shell command set by
2478defining ``CONFIGURE_SHELL_NO_COMMAND_CP`` when all
2479shell commands have been configured.
2480
2481**PROGRAMMING INFORMATION:**
2482
2483.. index:: rtems_shell_main_cp
2484
2485The ``cp`` command is implemented by a C language function which
2486has the following prototype:
2487.. code:: c
2488
2489    int rtems_shell_main_cp(
2490    int    argc,
2491    char \**argv
2492    );
2493
2494The configuration structure for the ``cp`` has the
2495following prototype:
2496.. code:: c
2497
2498    extern rtems_shell_cmd_t rtems_shell_CP_Command;
2499
2500**ORIGIN:**
2501
2502The implementation and portions of the documentation for this
2503command are from NetBSD 4.0.
2504
2505dd - convert and copy a file
2506----------------------------
2507.. index:: dd
2508
2509**SYNOPSYS:**
2510
2511.. code:: c
2512
2513    dd \[operands ...]
2514
2515**DESCRIPTION:**
2516
2517The dd utility copies the standard input to the standard output.
2518Input data is read and written in 512-byte blocks.  If input reads are
2519short, input from multiple reads are aggregated to form the output
2520block.  When finished, dd displays the number of complete and partial
2521input and output blocks and truncated input records to the standard
2522error output.
2523
2524The following operands are available:
2525
2526*bs=n*
2527    Set both input and output block size, superseding the ibs and obs
2528    operands.  If no conversion values other than noerror, notrunc or sync
2529    are specified, then each input block is copied to the output as a
2530    single block without any aggregation of short blocks.
2531
2532*cbs=n*
2533    Set the conversion record size to n bytes.  The conversion record size
2534    is required by the record oriented conversion values.
2535
2536*count=n*
2537    Copy only n input blocks.
2538
2539*files=n*
2540    Copy n input files before terminating.  This operand is only
2541    applicable when the input device is a tape.
2542
2543*ibs=n*
2544    Set the input block size to n bytes instead of the default 512.
2545
2546*if=file*
2547    Read input from file instead of the standard input.
2548
2549*obs=n*
2550    Set the output block size to n bytes instead of the default 512.
2551
2552*of=file*
2553    Write output to file instead of the standard output.  Any regular
2554    output file is truncated unless the notrunc conversion value is
2555    specified.  If an initial portion of the output file is skipped (see
2556    the seek operand) the output file is truncated at that point.
2557
2558*seek=n*
2559    Seek n blocks from the beginning of the output before copying.  On
2560    non-tape devices, a *lseek* operation is used.  Otherwise, existing
2561    blocks are read and the data discarded.  If the seek operation is past
2562    the end of file, space from the current end of file to the specified
2563    offset is filled with blocks of NUL bytes.
2564
2565*skip=n*
2566    Skip n blocks from the beginning of the input before copying.  On
2567    input which supports seeks, a *lseek* operation is used.  Otherwise,
2568    input data is read and discarded.  For pipes, the correct number of
2569    bytes is read.  For all other devices, the correct number of blocks is
2570    read without distinguishing between a partial or complete block being
2571    read.
2572
2573*progress=n*
2574    Switch on display of progress if n is set to any non-zero value.  This
2575    will cause a “.” to be printed (to the standard error output) for
2576    every n full or partial blocks written to the output file.
2577
2578*conv=value[,value...]*
2579    Where value is one of the symbols from the following list.
2580    *ascii, oldascii*
2581        The same as the unblock value except that characters are translated
2582        from EBCDIC to ASCII before the records are converted.  (These values
2583        imply unblock if the operand cbs is also specified.)  There are two
2584        conversion maps for ASCII.  The value ascii specifies the recom-
2585        mended one which is compatible with AT&T System V UNIX.  The value
2586        oldascii specifies the one used in historic AT&T and pre 4.3BSD-Reno
2587        systems.
2588    *block*
2589        Treats the input as a sequence of newline or end-of-file terminated
2590        variable length records independent of input and output block
2591        boundaries.  Any trailing newline character is discarded.  Each
2592        input record is converted to a fixed length output record where the
2593        length is specified by the cbs operand.  Input records shorter than
2594        the conversion record size are padded with spaces.  Input records
2595        longer than the conversion record size are truncated.  The number of
2596        truncated input records, if any, are reported to the standard error
2597        output at the completion of the copy.
2598    *ebcdic, ibm, oldebcdic, oldibm*
2599        The same as the block value except that characters are translated from
2600        ASCII to EBCDIC after the records are converted.  (These values imply
2601        block if the operand cbs is also specified.)  There are four
2602        conversion maps for EBCDIC.  The value ebcdic specifies the
2603        recommended one which is compatible with AT&T System V UNIX.  The
2604        value ibm is a slightly different mapping, which is compatible with
2605        the AT&T System V UNIX ibm value.  The values oldebcdic and oldibm are
2606        maps used in historic AT&T and pre 4.3BSD-Reno systems.
2607    *lcase*
2608        Transform uppercase characters into lowercase characters.
2609    *noerror*
2610        Do not stop processing on an input error.  When an input error occurs,
2611        a diagnostic message followed by the current input and output block
2612        counts will be written to the standard error output in the same format
2613        as the standard completion message.  If the sync conversion is also
2614        specified, any missing input data will be replaced with NUL bytes (or
2615        with spaces if a block oriented conversion value was specified) and
2616        processed as a normal input buffer.  If the sync conversion is not
2617        specified, the input block is omitted from the output.  On input files
2618        which are not tapes or pipes, the file offset will be positioned past
2619        the block in which the error occurred using lseek(2).
2620    *notrunc*
2621        Do not truncate the output file.  This will preserve any blocks in the
2622        output file not explicitly written by dd.  The notrunc value is not
2623        supported for tapes.
2624    *osync*
2625        Pad the final output block to the full output block size.  If the
2626        input file is not a multiple of the output block size after
2627        conversion, this conversion forces the final output block to be the
2628        same size as preceding blocks for use on devices that require
2629        regularly sized blocks to be written.  This option is incompatible
2630        with use of the bs=n block size specification.
2631    *sparse*
2632        If one or more non-final output blocks would consist solely of NUL
2633        bytes, try to seek the output file by the required space instead of
2634        filling them with NULs.  This results in a sparse file on some file
2635        systems.
2636    *swab*
2637        Swap every pair of input bytes.  If an input buffer has an odd number
2638        of bytes, the last byte will be ignored during swapping.
2639    *sync*
2640        Pad every input block to the input buffer size.  Spaces are used for
2641        pad bytes if a block oriented conversion value is specified, otherwise
2642        NUL bytes are used.
2643    *ucase*
2644        Transform lowercase characters into uppercase characters.
2645    *unblock*
2646        Treats the input as a sequence of fixed length records independent of
2647        input and output block boundaries.  The length of the input records is
2648        specified by the cbs operand.  Any trailing space characters are
2649        discarded and a newline character is appended.
2650
2651Where sizes are specified, a decimal number of bytes is expected.  Two
2652or more numbers may be separated by an “x” to indicate a product.
2653Each number may have one of the following optional suffixes:
2654
2655*b*
2656    Block; multiply by 512
2657
2658*k*
2659    Kibi; multiply by 1024 (1 KiB)
2660
2661*m*
2662    Mebi; multiply by 1048576 (1 MiB)
2663
2664*g*
2665    Gibi; multiply by 1073741824 (1 GiB)
2666
2667*t*
2668    Tebi; multiply by 1099511627776 (1 TiB)
2669
2670*w*
2671    Word; multiply by the number of bytes in an integer
2672
2673When finished, dd displays the number of complete and partial input
2674and output blocks, truncated input records and odd-length
2675byte-swapping ritten.  Partial output blocks to tape devices are
2676considered fatal errors.  Otherwise, the rest of the block will be
2677written.  Partial output blocks to character devices will produce a
2678warning message.  A truncated input block is one where a variable
2679length record oriented conversion value was specified and the input
2680line was too long to fit in the conversion record or was not newline
2681terminated.
2682
2683Normally, data resulting from input or conversion or both are
2684aggregated into output blocks of the specified size.  After the end of
2685input is reached, any remaining output is written as a block.  This
2686means that the final output block may be shorter than the output block
2687size.
2688
2689**EXIT STATUS:**
2690
2691This command returns 0 on success and non-zero if an error is encountered.
2692
2693**NOTES:**
2694
2695NONE
2696
2697**EXAMPLES:**
2698
2699The following is an example of how to use ``dd``:
2700.. code:: c
2701
2702    SHLL \[/] $ dd if=/nfs/boot-image of=/dev/hda1
2703
2704**CONFIGURATION:**
2705
2706.. index:: CONFIGURE_SHELL_NO_COMMAND_DD
2707.. index:: CONFIGURE_SHELL_COMMAND_DD
2708
2709This command is included in the default shell command set.  When
2710building a custom command set, define``CONFIGURE_SHELL_COMMAND_DD`` to have this command included.
2711
2712This command can be excluded from the shell command set by defining``CONFIGURE_SHELL_NO_COMMAND_DD`` when all shell commands have been
2713configured.
2714
2715**PROGRAMMING INFORMATION:**
2716
2717.. index:: rtems_shell_rtems_main_dd
2718
2719The ``dd`` command is implemented by a C language function which
2720has the following prototype:
2721.. code:: c
2722
2723    int rtems_shell_rtems_main_dd(
2724    int    argc,
2725    char \**argv
2726    );
2727
2728The configuration structure for the ``dd`` has the following
2729prototype:
2730.. code:: c
2731
2732    extern rtems_shell_cmd_t rtems_shell_DD_Command;
2733
2734debugrfs - debug RFS file system
2735--------------------------------
2736.. index:: debugrfs
2737
2738**SYNOPSYS:**
2739
2740.. code:: c
2741
2742    debugrfs \[-hl] path command \[options]
2743
2744**DESCRIPTION:**
2745
2746The command provides debugging information for the RFS file system.
2747
2748The options are:
2749
2750*-h*
2751    Print a help message.
2752
2753*-l*
2754    List the commands.
2755
2756*path*
2757    Path to the mounted RFS file system. The file system has to be mounted
2758    to view to use this command.
2759
2760The commands are:
2761
2762*block start \[end]*
2763    Display the contents of the blocks from start to end.
2764
2765*data*
2766    Display the file system data and configuration.
2767
2768*dir bno*
2769    Process the block as a directory displaying the entries.
2770
2771*group start \[end]*
2772    Display the group data from the start group to the end group.
2773
2774*inode \[-aef] \[start] \[end]*
2775    Display the inodes between start and end. If no start and end is
2776    provides all inodes are displayed.
2777    *-a*
2778        Display all inodes. That is allocated and unallocated inodes.
2779    *-e*
2780        Search and display on inodes that have an error.
2781    *-f*
2782        Force display of inodes, even when in error.
2783
2784**EXIT STATUS:**
2785
2786This command returns 0 on success and non-zero if an error is encountered.
2787
2788**NOTES:**
2789
2790NONE
2791
2792**EXAMPLES:**
2793
2794The following is an example of how to use ``debugrfs``:
2795.. code:: c
2796
2797    SHLL \[/] $ debugrfs /c data
2798
2799**CONFIGURATION:**
2800
2801.. index:: CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS
2802.. index:: CONFIGURE_SHELL_COMMAND_DEBUGRFS
2803
2804This command is included in the default shell command set.
2805When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DEBUGRFS`` to have this
2806command included.
2807
2808This command can be excluded from the shell command set by
2809defining ``CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS`` when all
2810shell commands have been configured.
2811
2812**PROGRAMMING INFORMATION:**
2813
2814.. index:: rtems_shell_rtems_main_debugrfs
2815
2816The ``debugrfs`` command is implemented by a C language function which
2817has the following prototype:
2818.. code:: c
2819
2820    int rtems_shell_rtems_main_debugrfs(
2821    int    argc,
2822    char \**argv
2823    );
2824
2825The configuration structure for ``debugrfs`` has the following
2826prototype:
2827.. code:: c
2828
2829    extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command;
2830
2831df - display file system disk space usage
2832-----------------------------------------
2833.. index:: df
2834
2835**SYNOPSYS:**
2836
2837.. code:: c
2838
2839    df \[-h] \[-B block_size]
2840
2841**DESCRIPTION:**
2842
2843This command print disk space usage for mounted file systems.
2844
2845**EXIT STATUS:**
2846
2847This command returns 0 on success and non-zero if an error is encountered.
2848
2849**NOTES:**
2850
2851NONE
2852
2853**EXAMPLES:**
2854
2855The following is an example of how to use ``df``:
2856.. code:: c
2857
2858    SHLL \[/] $ df -B 4K
2859    Filesystem     4K-blocks        Used   Available       Use%     Mounted on
2860    /dev/rda               124         1         124         0%   /mnt/ramdisk
2861    SHLL \[/] $ df
2862    Filesystem     1K-blocks        Used   Available       Use%     Mounted on
2863    /dev/rda               495         1         494         0%   /mnt/ramdisk
2864    SHLL \[/] $ df -h
2865    Filesystem     Size             Used   Available       Use%     Mounted on
2866    /dev/rda              495K        1K        494K         0%   /mnt/ramdisk
2867
2868**CONFIGURATION:**
2869
2870.. index:: CONFIGURE_SHELL_NO_COMMAND_DF
2871.. index:: CONFIGURE_SHELL_COMMAND_DF
2872
2873This command is included in the default shell command set.
2874When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DF`` to have this
2875command included.
2876
2877This command can be excluded from the shell command set by
2878defining ``CONFIGURE_SHELL_NO_COMMAND_DF`` when all
2879shell commands have been configured.
2880
2881**PROGRAMMING INFORMATION:**
2882
2883.. index:: rtems_shell_rtems_main_df
2884
2885The ``df`` is implemented by a C language function
2886which has the following prototype:
2887.. code:: c
2888
2889    int rtems_shell_main_df(
2890    int argc,
2891    char \**argv
2892    );
2893
2894The configuration structure for the ``df`` has the
2895following prototype:
2896.. code:: c
2897
2898    extern rtems_shell_cmd_t rtems_shell_DF_Command;
2899
2900dir - alias for ls
2901------------------
2902.. index:: dir
2903
2904**SYNOPSYS:**
2905
2906.. code:: c
2907
2908    dir \[dir]
2909
2910**DESCRIPTION:**
2911
2912This command is an alias or alternate name for the ``ls``.
2913See :ref:`ls <File-and-Directory-Commands-ls-_002d-list-files-in-the-directory>`
2914for more information.
2915
2916**EXIT STATUS:**
2917
2918This command returns 0 on success and non-zero if an error is encountered.
2919
2920**NOTES:**
2921
2922NONE
2923
2924**EXAMPLES:**
2925
2926The following is an example of how to use ``dir``:
2927.. code:: c
2928
2929    SHLL \[/] $ dir
2930    drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
2931    drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
2932    2 files 1608 bytes occupied
2933    SHLL \[/] $ dir etc
2934    -rw-r--r--   1   root   root         102 Jan 01 00:00 passwd
2935    -rw-r--r--   1   root   root          42 Jan 01 00:00 group
2936    -rw-r--r--   1   root   root          30 Jan 01 00:00 issue
2937    -rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net
2938    4 files 202 bytes occupied
2939
2940**CONFIGURATION:**
2941
2942.. index:: CONFIGURE_SHELL_NO_COMMAND_DIR
2943.. index:: CONFIGURE_SHELL_COMMAND_DIR
2944
2945This command is included in the default shell command set.
2946When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DIR`` to have this
2947command included.
2948
2949This command can be excluded from the shell command set by
2950defining ``CONFIGURE_SHELL_NO_COMMAND_DIR`` when all
2951shell commands have been configured.
2952
2953**PROGRAMMING INFORMATION:**
2954
2955.. index:: rtems_shell_rtems_main_dir
2956
2957The ``dir`` is implemented by a C language function
2958which has the following prototype:
2959.. code:: c
2960
2961    int rtems_shell_rtems_main_dir(
2962    int    argc,
2963    char \**argv
2964    );
2965
2966The configuration structure for the ``dir`` has the
2967following prototype:
2968.. code:: c
2969
2970    extern rtems_shell_cmd_t rtems_shell_DIR_Command;
2971
2972fdisk - format disk
2973-------------------
2974.. index:: fdisk
2975
2976**SYNOPSYS:**
2977
2978.. code:: c
2979
2980    fdisk
2981
2982**CONFIGURATION:**
2983
2984.. index:: CONFIGURE_SHELL_NO_COMMAND_FDISK
2985.. index:: CONFIGURE_SHELL_COMMAND_FDISK
2986
2987This command is included in the default shell command set.
2988When building a custom command set, define``CONFIGURE_SHELL_COMMAND_FDISK`` to have this
2989command included.
2990
2991This command can be excluded from the shell command set by
2992defining ``CONFIGURE_SHELL_NO_COMMAND_FDISK`` when all
2993shell commands have been configured.
2994
2995hexdump - ascii/dec/hex/octal dump
2996----------------------------------
2997.. index:: hexdump
2998
2999**SYNOPSYS:**
3000
3001.. code:: c
3002
3003    hexdump \[-bcCdovx] \[-e format_string] \[-f format_file] \[-n length]
3004    \[-s skip] file ...
3005
3006**DESCRIPTION:**
3007
3008The hexdump utility is a filter which displays the specified files, or
3009the standard input, if no files are specified, in a user specified
3010format.
3011
3012The options are as follows:
3013
3014*-b*
3015    One-byte octal display.  Display the input offset in hexadecimal,
3016    followed by sixteen space-separated, three column, zero-filled, bytes
3017    of input data, in octal, per line.
3018
3019*-c*
3020    One-byte character display.  Display the input offset in hexadecimal,
3021    followed by sixteen space-separated, three column, space-filled,
3022    characters of input data per line.
3023
3024*-C*
3025    Canonical hex+ASCII display.  Display the input offset in hexadecimal,
3026    followed by sixteen space-separated, two column, hexadecimal bytes,
3027    followed by the same sixteen bytes in %_p format enclosed in “|”
3028    characters.
3029
3030*-d*
3031    Two-byte decimal display.  Display the input offset in hexadecimal,
3032    followed by eight space-separated, five column, zero-filled, two-byte
3033    units of input data, in unsigned decimal, per line.
3034
3035*-e format_string*
3036    Specify a format string to be used for displaying data.
3037
3038*-f format_file*
3039    Specify a file that contains one or more newline separated format
3040    strings.  Empty lines and lines whose first non-blank character is a
3041    hash mark (#) are ignored.
3042
3043*-n length*
3044    Interpret only length bytes of input.
3045
3046*-o*
3047    Two-byte octal display.  Display the input offset in hexadecimal,
3048    followed by eight space-separated, six column, zerofilled, two byte
3049    quantities of input data, in octal, per line.
3050
3051*-s offset*
3052    Skip offset bytes from the beginning of the input.  By default, offset
3053    is interpreted as a decimal number.  With a leading 0x or 0X, offset
3054    is interpreted as a hexadecimal number, otherwise, with a leading 0,
3055    offset is interpreted as an octal number.  Appending the character b,
3056    k, or m to offset causes it to be interpreted as a multiple of 512,
3057    1024, or 1048576, respectively.
3058
3059*-v*
3060    The -v option causes hexdump to display all input data.  Without the
3061    -v option, any number of groups of output lines, which would be
3062    identical to the immediately preceding group of output lines (except
3063    for the input offsets), are replaced with a line containing a single
3064    asterisk.
3065
3066*-x*
3067    Two-byte hexadecimal display.  Display the input offset in
3068    hexadecimal, followed by eight, space separated, four column,
3069    zero-filled, two-byte quantities of input data, in hexadecimal, per
3070    line.
3071
3072For each input file, hexdump sequentially copies the input to standard
3073output, transforming the data according to the format strings
3074specified by the -e and -f options, in the order that they were
3075specified.
3076
3077*Formats*
3078
3079A format string contains any number of format units, separated by
3080whitespace.  A format unit contains up to three items: an iteration
3081count, a byte count, and a format.
3082
3083The iteration count is an optional positive integer, which defaults to
3084one.  Each format is applied iteration count times.
3085
3086The byte count is an optional positive integer.  If specified it
3087defines the number of bytes to be interpreted by each iteration of the
3088format.
3089
3090If an iteration count and/or a byte count is specified, a single slash
3091must be placed after the iteration count and/or before the byte count
3092to disambiguate them.  Any whitespace before or after the slash is
3093ignored.
3094
3095The format is required and must be surrounded by double quote (“ “)
3096marks.  It is interpreted as a fprintf-style format string (see*fprintf*), with the following exceptions:
3097
3098- An asterisk (\*) may not be used as a field width or precision.
3099
3100- A byte count or field precision is required for each “s” con-
3101  version character (unlike the fprintf(3) default which prints the
3102  entire string if the precision is unspecified).
3103
3104- The conversion characters “h”, “l”, “n”, “p” and “q” are not
3105  supported.
3106
3107- The single character escape sequences described in the C standard
3108  are supported:
3109      NUL                  \\0
3110      <alert character>    \\a
3111      <backspace>          \\b
3112      <form-feed>          \\f
3113      <newline>            \\n
3114      <carriage return>    \\r
3115      <tab>                \\t
3116      <vertical tab>       \\v
3117
3118Hexdump also supports the following additional conversion strings:
3119
3120*_a[dox]*
3121    Display the input offset, cumulative across input files, of the next
3122    byte to be displayed.  The appended characters d, o, and x specify the
3123    display base as decimal, octal or hexadecimal respectively.
3124
3125*_A[dox]*
3126    Identical to the _a conversion string except that it is only performed
3127    once, when all of the input data has been processed.
3128
3129*_c*
3130    Output characters in the default character set.  Nonprinting
3131    characters are displayed in three character, zero-padded octal, except
3132    for those representable by standard escape notation (see above), which
3133    are displayed as two character strings.
3134
3135*_p*
3136    Output characters in the default character set.  Nonprinting
3137    characters are displayed as a single “.”.
3138
3139*_u*
3140    Output US ASCII characters, with the exception that control characters
3141    are displayed using the following, lower-case, names.  Characters
3142    greater than 0xff, hexadecimal, are displayed as hexadecimal
3143    strings.
3144    000 nul  001 soh  002 stx  003 etx  004 eot  005 enq
3145    006 ack  007 bel  008 bs   009 ht   00A lf   00B vt
3146    00C ff   00D cr   00E so   00F si   010 dle  011 dc1
3147    012 dc2  013 dc3  014 dc4  015 nak  016 syn  017 etb
3148    018 can  019 em   01A sub  01B esc  01C fs   01D gs
3149    01E rs   01F us   07F del
3150
3151The default and supported byte counts for the conversion characters
3152are as follows:
3153
3154    %_c, %_p, %_u, %c       One byte counts only.
3155    %d, %i, %o, %u, %X, %x  Four byte default, one, two, four
3156    and eight byte counts supported.
3157    %E, %e, %f, %G, %g      Eight byte default, four byte
3158    counts supported.
3159
3160The amount of data interpreted by each format string is the sum of the
3161data required by each format unit, which is the iteration count times
3162the byte count, or the iteration count times the number of bytes
3163required by the format if the byte count is not specified.
3164
3165The input is manipulated in “blocks”, where a block is defined as
3166the largest amount of data specified by any format string.  Format
3167strings interpreting less than an input block’s worth of data, whose
3168last format unit both interprets some number of bytes and does not
3169have a specified iteration count, have the iteration count incremented
3170until the entire input block has been processed or there is not enough
3171data remaining in the block to satisfy the format string.
3172
3173If, either as a result of user specification or hexdump modifying the
3174iteration count as described above, an iteration count is greater than
3175one, no trailing whitespace characters are output during the last
3176iteration.
3177
3178It is an error to specify a byte count as well as multiple conversion
3179characters or strings unless all but one of the conversion characters
3180or strings is _a or _A.
3181
3182If, as a result of the specification of the -n option or end-of-file
3183being reached, input data only partially satisfies a format string,
3184the input block is zero-padded sufficiently to display all available
3185data (i.e. any format units overlapping the end of data will display
3186some num- ber of the zero bytes).
3187
3188Further output by such format strings is replaced by an equivalent
3189number of spaces.  An equivalent number of spaces is defined as the
3190number of spaces output by an s conversion character with the same
3191field width and precision as the original conversion character or
3192conversion string but with any “+”, “ ”, “#” conversion flag
3193characters removed, and ref- erencing a NULL string.
3194
3195If no format strings are specified, the default display is equivalent
3196to specifying the -x option.
3197
3198**EXIT STATUS:**
3199
3200This command returns 0 on success and non-zero if an error is encountered.
3201
3202**NOTES:**
3203
3204NONE
3205
3206**EXAMPLES:**
3207
3208The following is an example of how to use ``hexdump``:
3209.. code:: c
3210
3211    SHLL \[/] $ hexdump -C -n 512 /dev/hda1
3212
3213**CONFIGURATION:**
3214
3215.. index:: CONFIGURE_SHELL_NO_COMMAND_HEXDUMP
3216.. index:: CONFIGURE_SHELL_COMMAND_HEXDUMP
3217
3218This command is included in the default shell command set.  When
3219building a custom command set, define``CONFIGURE_SHELL_COMMAND_HEXDUMP`` to have this command included.
3220
3221This command can be excluded from the shell command set by defining``CONFIGURE_SHELL_NO_COMMAND_HEXDUMP`` when all shell commands have
3222been configured.
3223
3224**PROGRAMMING INFORMATION:**
3225
3226.. index:: rtems_shell_rtems_main_hexdump
3227
3228The ``hexdump`` command is implemented by a C language function
3229which has the following prototype:
3230.. code:: c
3231
3232    int rtems_shell_rtems_main_hexdump(
3233    int    argc,
3234    char \**argv
3235    );
3236
3237The configuration structure for the ``hexdump`` has the following
3238prototype:
3239.. code:: c
3240
3241    extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command;
3242
3243ln - make links
3244---------------
3245.. index:: ln
3246
3247**SYNOPSYS:**
3248
3249.. code:: c
3250
3251    ln \[-fhinsv] source_file \[target_file]
3252    ln \[-fhinsv] source_file ... target_dir
3253
3254**DESCRIPTION:**
3255
3256The ln utility creates a new directory entry (linked file) which has
3257the same modes as the original file.  It is useful for maintaining
3258multiple copies of a file in many places at once without using up
3259storage for the “copies”; instead, a link “points” to the original
3260copy.  There are two types of links; hard links and symbolic links.
3261How a link “points” to a file is one of the differences between a
3262hard or symbolic link.
3263
3264The options are as follows:
3265
3266*-f*
3267    Unlink any already existing file, permitting the link to occur.
3268
3269*-h*
3270    If the target_file or target_dir is a symbolic link, do not follow it.
3271    This is most useful with the -f option, to replace a symlink which may
3272    point to a directory.
3273
3274*-i*
3275    Cause ln to write a prompt to standard error if the target file
3276    exists.  If the response from the standard input begins with the
3277    character ‘y’ or ‘Y’, then unlink the target file so that the link may
3278    occur.  Otherwise, do not attempt the link.  (The -i option overrides
3279    any previous -f options.)
3280
3281*-n*
3282    Same as -h, for compatibility with other ln implementations.
3283
3284*-s*
3285    Create a symbolic link.
3286
3287*-v*
3288    Cause ln to be verbose, showing files as they are processed.
3289
3290By default ln makes hard links.  A hard link to a file is
3291indistinguishable from the original directory entry; any changes to a
3292file are effective independent of the name used to reference the file.
3293Hard links may not normally refer to directories and may not span file
3294systems.
3295
3296A symbolic link contains the name of the file to which it is linked.
3297The referenced file is used when an *open* operation is performed on
3298the link.  A *stat* on a symbolic link will return the linked-to
3299file; an *lstat* must be done to obtain information about the link.
3300The *readlink* call may be used to read the contents of a symbolic
3301link.  Symbolic links may span file systems and may refer to
3302directories.
3303
3304Given one or two arguments, ln creates a link to an existing file
3305source_file.  If target_file is given, the link has that name;
3306target_file may also be a directory in which to place the link;
3307otherwise it is placed in the current directory.  If only the
3308directory is specified, the link will be made to the last component of
3309source_file.
3310
3311Given more than two arguments, ln makes links in target_dir to all the
3312named source files.  The links made will have the same name as the
3313files being linked to.
3314
3315**EXIT STATUS:**
3316
3317The ``ln`` utility exits 0 on success, and >0 if an error occurs.
3318
3319**NOTES:**
3320
3321NONE
3322
3323**EXAMPLES:**
3324
3325.. code:: c
3326
3327    SHLL \[/] ln -s /dev/console /dev/con1
3328
3329**CONFIGURATION:**
3330
3331.. index:: CONFIGURE_SHELL_NO_COMMAND_LN
3332.. index:: CONFIGURE_SHELL_COMMAND_LN
3333
3334This command is included in the default shell command set.  When
3335building a custom command set, define``CONFIGURE_SHELL_COMMAND_LN`` to have this command included.
3336
3337This command can be excluded from the shell command set by
3338defining ``CONFIGURE_SHELL_NO_COMMAND_LN`` when all
3339shell commands have been configured.
3340
3341**PROGRAMMING INFORMATION:**
3342
3343.. index:: rtems_shell_rtems_main_ln
3344
3345The ``ln`` command is implemented by a C language function which
3346has the following prototype:
3347.. code:: c
3348
3349    int rtems_shell_rtems_main_ln(
3350    int    argc,
3351    char \**argv
3352    );
3353
3354The configuration structure for the ``ln`` has the following
3355prototype:
3356.. code:: c
3357
3358    extern rtems_shell_cmd_t rtems_shell_LN_Command;
3359
3360**ORIGIN:**
3361
3362The implementation and portions of the documentation for this command
3363are from NetBSD 4.0.
3364
3365.. _File-and-Directory-Commands-ls-_002d-list-files-in-the-directory:
3366
3367ls - list files in the directory
3368--------------------------------
3369.. index:: ls
3370
3371**SYNOPSYS:**
3372
3373.. code:: c
3374
3375    ls \[dir]
3376
3377**DESCRIPTION:**
3378
3379This command displays the contents of the specified directory.  If
3380no arguments are given, then it displays the contents of the current
3381working directory.
3382
3383**EXIT STATUS:**
3384
3385This command returns 0 on success and non-zero if an error is encountered.
3386
3387**NOTES:**
3388
3389This command currently does not display information on a set of
3390files like the POSIX ls(1).  It only displays the contents of
3391entire directories.
3392
3393**EXAMPLES:**
3394
3395The following is an example of how to use ``ls``:
3396.. code:: c
3397
3398    SHLL \[/] $ ls
3399    drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
3400    drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
3401    2 files 1608 bytes occupied
3402    SHLL \[/] $ ls etc
3403    -rw-r--r--   1   root   root         102 Jan 01 00:00 passwd
3404    -rw-r--r--   1   root   root          42 Jan 01 00:00 group
3405    -rw-r--r--   1   root   root          30 Jan 01 00:00 issue
3406    -rw-r--r--   1   root   root          28 Jan 01 00:00 issue.net
3407    4 files 202 bytes occupied
3408    SHLL \[/] $ ls dev etc
3409    -rwxr-xr-x   1  rtems   root           0 Jan 01 00:00 console
3410    -rwxr-xr-x   1   root   root           0 Jan 01 00:00 console_b
3411
3412**CONFIGURATION:**
3413
3414.. index:: CONFIGURE_SHELL_NO_COMMAND_LS
3415.. index:: CONFIGURE_SHELL_COMMAND_LS
3416
3417This command is included in the default shell command set.
3418When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LS`` to have this
3419command included.
3420
3421This command can be excluded from the shell command set by
3422defining ``CONFIGURE_SHELL_NO_COMMAND_LS`` when all
3423shell commands have been configured.
3424
3425**PROGRAMMING INFORMATION:**
3426
3427.. index:: rtems_shell_rtems_main_ls
3428
3429The ``ls`` is implemented by a C language function
3430which has the following prototype:
3431.. code:: c
3432
3433    int rtems_shell_rtems_main_ls(
3434    int    argc,
3435    char \**argv
3436    );
3437
3438The configuration structure for the ``ls`` has the
3439following prototype:
3440.. code:: c
3441
3442    extern rtems_shell_cmd_t rtems_shell_LS_Command;
3443
3444md5 - compute the Md5 hash of a file or list of files
3445-----------------------------------------------------
3446.. index:: md5
3447
3448**SYNOPSYS:**
3449
3450.. code:: c
3451
3452    md5 <files>
3453
3454**DESCRIPTION:**
3455
3456This command prints the MD5 of a file. You can provide one or more
3457files on the command line and a hash for each file is printed in a
3458single line of output.
3459
3460**EXIT STATUS:**
3461
3462This command returns 0 on success and non-zero if an error is encountered.
3463
3464**NOTES:**
3465
3466NONE
3467
3468**EXAMPLES:**
3469
3470The following is an example of how to use ``md5``:
3471.. code:: c
3472
3473    SHLL \[/] $ md5 shell-init
3474    MD5 (shell-init) = 43b4d2e71b47db79eae679a2efeacf31
3475
3476**CONFIGURATION:**
3477
3478.. index:: CONFIGURE_SHELL_NO_COMMAND_MD5
3479.. index:: CONFIGURE_SHELL_COMMAND_MD5
3480
3481This command is included in the default shell command set.
3482When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MD5`` to have this
3483command included.
3484
3485This command can be excluded from the shell command set by
3486defining ``CONFIGURE_SHELL_NO_COMMAND_MD5`` when all
3487shell commands have been configured.
3488
3489**PROGRAMMING INFORMATION:**
3490
3491.. index:: rtems_shell_rtems_main_md5
3492
3493The ``df`` is implemented by a C language function
3494which has the following prototype:
3495.. code:: c
3496
3497    int rtems_shell_main_md5(
3498    int argc,
3499    char \**argv
3500    );
3501
3502The configuration structure for the ``md5`` has the
3503following prototype:
3504.. code:: c
3505
3506    extern rtems_shell_cmd_t rtems_shell_MD5_Command;
3507
3508mkdir - create a directory
3509--------------------------
3510.. index:: mkdir
3511
3512**SYNOPSYS:**
3513
3514.. code:: c
3515
3516    mkdir  dir \[dir1 .. dirN]
3517
3518**DESCRIPTION:**
3519
3520This command creates the set of directories in the order they
3521are specified on the command line.  If an error is encountered
3522making one of the directories, the command will continue to
3523attempt to create the remaining directories on the command line.
3524
3525**EXIT STATUS:**
3526
3527This command returns 0 on success and non-zero if an error is encountered.
3528
3529**NOTES:**
3530
3531If this command is invoked with no arguments, nothing occurs.
3532
3533The user must have sufficient permissions to create the directory.
3534For the ``fileio`` test provided with RTEMS, this means the user
3535must login as ``root`` not ``rtems``.
3536
3537**EXAMPLES:**
3538
3539The following is an example of how to use ``mkdir``:
3540.. code:: c
3541
3542    SHLL \[/] # ls
3543    drwxr-xr-x   1   root   root         536 Jan 01 00:00 dev/
3544    drwxr-xr-x   1   root   root        1072 Jan 01 00:00 etc/
3545    2 files 1608 bytes occupied
3546    SHLL \[/] # mkdir joel
3547    SHLL \[/] # ls joel
3548    0 files 0 bytes occupied
3549    SHLL \[/] # cp etc/passwd joel
3550    SHLL \[/] # ls joel
3551    -rw-r--r--   1   root   root         102 Jan 01 00:02 passwd
3552    1 files 102 bytes occupied
3553
3554**CONFIGURATION:**
3555
3556.. index:: CONFIGURE_SHELL_NO_COMMAND_MKDIR
3557.. index:: CONFIGURE_SHELL_COMMAND_MKDIR
3558
3559This command is included in the default shell command set.
3560When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKDIR`` to have this
3561command included.
3562
3563This command can be excluded from the shell command set by
3564defining ``CONFIGURE_SHELL_NO_COMMAND_MKDIR`` when all
3565shell commands have been configured.
3566
3567**PROGRAMMING INFORMATION:**
3568
3569.. index:: rtems_shell_rtems_main_mkdir
3570
3571The ``mkdir`` is implemented by a C language function
3572which has the following prototype:
3573.. code:: c
3574
3575    int rtems_shell_rtems_main_mkdir(
3576    int    argc,
3577    char \**argv
3578    );
3579
3580The configuration structure for the ``mkdir`` has the
3581following prototype:
3582.. code:: c
3583
3584    extern rtems_shell_cmd_t rtems_shell_MKDIR_Command;
3585
3586mldos - DOSFS file system format
3587--------------------------------
3588.. index:: pwd
3589
3590**SYNOPSYS:**
3591
3592.. code:: c
3593
3594    mkdir \[-V label] \[-s sectors/cluster] \[-r size] \[-v] path
3595
3596**DESCRIPTION:**
3597
3598This command formats a block device entry with the DOSFS file system.
3599
3600*-V label*
3601
3602*-s sectors/cluster*
3603
3604*-r size*
3605
3606**EXIT STATUS:**
3607
3608This command returns 0 on success and non-zero if an error is encountered.
3609
3610**NOTES:**
3611
3612NONE
3613
3614**EXAMPLES:**
3615
3616The following is an example of how to use ``mkdos``:
3617.. code:: c
3618
3619    SHLL \[/] $ mkdos /dev/rda1
3620
3621**CONFIGURATION:**
3622
3623.. index:: CONFIGURE_SHELL_NO_COMMAND_MKDOS
3624.. index:: CONFIGURE_SHELL_COMMAND_MKDOS
3625
3626This command is included in the default shell command set.
3627When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKDOS`` to have this
3628command included.
3629
3630This command can be excluded from the shell command set by
3631defining ``CONFIGURE_SHELL_NO_COMMAND_MKDOS`` when all
3632shell commands have been configured.
3633
3634**PROGRAMMING INFORMATION:**
3635
3636.. index:: rtems_shell_rtems_main_mkdos
3637
3638The ``mkdos`` is implemented by a C language function
3639which has the following prototype:
3640.. code:: c
3641
3642    int rtems_shell_rtems_main_mkdos(
3643    int    argc,
3644    char \**argv
3645    );
3646
3647The configuration structure for the ``mkdos`` has the
3648following prototype:
3649.. code:: c
3650
3651    extern rtems_shell_cmd_t rtems_shell_MKDOS_Command;
3652
3653mknod - make device special file
3654--------------------------------
3655.. index:: mknod
3656
3657**SYNOPSYS:**
3658
3659.. code:: c
3660
3661    mknod \[-rR] \[-F fmt] \[-g gid] \[-m mode] \[-u uid] name \[c | b]
3662    \[driver | major] minor
3663    mknod \[-rR] \[-F fmt] \[-g gid] \[-m mode] \[-u uid] name \[c | b]
3664    major unit subunit
3665    mknod \[-rR] \[-g gid] \[-m mode] \[-u uid] name \[c | b] number
3666    mknod \[-rR] \[-g gid] \[-m mode] \[-u uid] name p
3667
3668**DESCRIPTION:**
3669
3670The mknod command creates device special files, or fifos.  Normally
3671the shell script /dev/MAKEDEV is used to create special files for
3672commonly known devices; it executes mknod with the appropriate
3673arguments and can make all the files required for the device.
3674
3675To make nodes manually, the arguments are:
3676
3677*-r*
3678    Replace an existing file if its type is incorrect.
3679
3680*-R*
3681    Replace an existing file if its type is incorrect.  Correct the
3682    mode, user and group.
3683
3684*-g gid*
3685    Specify the group for the device node.  The gid operand may be a
3686    numeric group ID or a group name.  If a group name is also a numeric
3687    group ID, the operand is used as a group name.  Precede a numeric
3688    group ID with a # to stop it being treated as a name.
3689
3690*-m mode*
3691    Specify the mode for the device node.  The mode may be absolute or
3692    symbolic, see *chmod*.
3693
3694*-u uid*
3695    Specify the user for the device node.  The uid operand may be a
3696    numeric user ID or a user name.  If a user name is also a numeric user
3697    ID, the operand is used as a user name.  Precede a numeric user ID
3698    with a # to stop it being treated as a name.
3699
3700*name*
3701    Device name, for example “tty” for a termios serial device or “hd”
3702    for a disk.
3703
3704*b | c | p*
3705    Type of device.  If the device is a block type device such as a tape
3706    or disk drive which needs both cooked and raw special files, the type
3707    is b.  All other devices are character type devices, such as terminal
3708    and pseudo devices, and are type c.  Specifying p creates fifo files.
3709
3710*driver | major*
3711    The major device number is an integer number which tells the kernel
3712    which device driver entry point to use.  If the device driver is
3713    configured into the current kernel it may be specified by driver name
3714    or major number.
3715
3716*minor*
3717    The minor device number tells the kernel which one of several similar
3718    devices the node corresponds to; for example, it may be a specific
3719    serial port or pty.
3720
3721*unit and subunit*
3722    The unit and subunit numbers select a subset of a device; for example,
3723    the unit may specify a particular disk, and the subunit a partition on
3724    that disk.  (Currently this form of specification is only supported
3725    by the bsdos format, for compatibility with the BSD/OS mknod).
3726
3727*number*
3728    A single opaque device number.  Useful for netbooted computers which
3729    require device numbers packed in a format that isn’t supported by
3730    -F.
3731
3732**EXIT STATUS:**
3733
3734The ``mknod`` utility exits 0 on success, and >0 if an error occurs.
3735
3736**NOTES:**
3737
3738NONE
3739
3740**EXAMPLES:**
3741
3742.. code:: c
3743
3744    SHLL \[/] mknod c 3 0 /dev/ttyS10
3745
3746**CONFIGURATION:**
3747
3748.. index:: CONFIGURE_SHELL_NO_COMMAND_MKNOD
3749.. index:: CONFIGURE_SHELL_COMMAND_MKNOD
3750
3751This command is included in the default shell command set.  When
3752building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKNOD`` to have this command included.
3753
3754This command can be excluded from the shell command set by
3755defining ``CONFIGURE_SHELL_NO_COMMAND_MKNOD`` when all
3756shell commands have been configured.
3757
3758**PROGRAMMING INFORMATION:**
3759
3760.. index:: rtems_shell_rtems_main_mknod
3761
3762The ``mknod`` command is implemented by a C language function which
3763has the following prototype:
3764.. code:: c
3765
3766    int rtems_shell_rtems_main_mknod(
3767    int    argc,
3768    char \**argv
3769    );
3770
3771The configuration structure for the ``mknod`` has the following
3772prototype:
3773.. code:: c
3774
3775    extern rtems_shell_cmd_t rtems_shell_MKNOD_Command;
3776
3777**ORIGIN:**
3778
3779The implementation and portions of the documentation for this command
3780are from NetBSD 4.0.
3781
3782mkrfs - format RFS file system
3783------------------------------
3784.. index:: mkrfs
3785
3786**SYNOPSYS:**
3787
3788.. code:: c
3789
3790    mkrfs \[-vsbiIo] device
3791
3792**DESCRIPTION:**
3793
3794Format the block device with the RTEMS File System (RFS). The default
3795configuration with not parameters selects a suitable block size based
3796on the size of the media being formatted.
3797
3798The media is broken up into groups of blocks. The number of blocks in
3799a group is based on the number of bits a block contains. The large a
3800block the more blocks a group contains and the fewer groups in the
3801file system.
3802
3803The following options are provided:
3804
3805*-v*
3806    Display configuration and progress of the format.
3807
3808*-s*
3809    Set the block size in bytes.
3810
3811*-b*
3812    The number of blocks in a group. The block count must be equal or less
3813    than the number of bits in a block.
3814
3815*-i*
3816    Number of inodes in a group. The inode count must be equal or less
3817    than the number of bits in a block.
3818
3819*-I*
3820    Initialise the inodes. The default is not to initialise the inodes and
3821    to rely on the inode being initialised when allocated. Initialising
3822    the inode table helps recovery if a problem appears.
3823
3824*-o*
3825    Integer percentage of the media used by inodes. The default is 1%.
3826
3827*device*
3828    Path of the device to format.
3829
3830**EXIT STATUS:**
3831
3832This command returns 0 on success and non-zero if an error is encountered.
3833
3834**NOTES:**
3835
3836NONE
3837
3838**EXAMPLES:**
3839
3840The following is an example of how to use ``mkrfs``:
3841.. code:: c
3842
3843    SHLL \[/] $ mkrfs /dev/fdda
3844
3845**CONFIGURATION:**
3846
3847.. index:: CONFIGURE_SHELL_NO_COMMAND_MKRFS
3848.. index:: CONFIGURE_SHELL_COMMAND_MKRFS
3849
3850This command is included in the default shell command set.
3851When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MKRFS`` to have this
3852command included.
3853
3854This command can be excluded from the shell command set by
3855defining ``CONFIGURE_SHELL_NO_COMMAND_MKRFS`` when all
3856shell commands have been configured.
3857
3858**PROGRAMMING INFORMATION:**
3859
3860.. index:: rtems_shell_rtems_main_mkrfs
3861
3862The ``mkrfs`` command is implemented by a C language function which
3863has the following prototype:
3864.. code:: c
3865
3866    int rtems_shell_rtems_main_mkrfs(
3867    int    argc,
3868    char \**argv
3869    );
3870
3871The configuration structure for ``mkrfs`` has the following
3872prototype:
3873.. code:: c
3874
3875    extern rtems_shell_cmd_t rtems_shell_MKRFS_Command;
3876
3877mount - mount disk
3878------------------
3879.. index:: mount
3880
3881**SYNOPSYS:**
3882
3883.. code:: c
3884
3885    mount \[-t fstype] \[-r] \[-L] device path
3886
3887**DESCRIPTION:**
3888
3889The ``mount`` command will mount a block device to a mount point
3890using the specified file system. The files systems are:
3891
3892- msdos - MSDOS File System
3893
3894- tftp  - TFTP Network File System
3895
3896- ftp   - FTP Network File System
3897
3898- nfs   - Network File System
3899
3900- rfs   - RTEMS File System
3901
3902When the file system type is ’msdos’ or ’rfs’ the driver is a "block
3903device driver" node present in the file system. The driver is ignored
3904with the ’tftp’ and ’ftp’ file systems. For the ’nfs’ file system the
3905driver is the ’host:/path’ string that described NFS host and the
3906exported file system path.
3907
3908**EXIT STATUS:**
3909
3910This command returns 0 on success and non-zero if an error is encountered.
3911
3912**NOTES:**
3913
3914The mount point must exist.
3915
3916The services offered by each file-system vary. For example you cannot list the
3917directory of a TFTP file-system as this server is not provided in the TFTP
3918protocol. You need to check each file-system’s documentation for the services
3919provided.
3920
3921**EXAMPLES:**
3922
3923Mount the Flash Disk driver to the ’/fd’ mount point:
3924.. code:: c
3925
3926    SHLL \[/] $ mount -t msdos /dev/flashdisk0 /fd
3927
3928Mount the NFS file system exported path ’bar’ by host ’foo’:
3929.. code:: c
3930
3931    $ mount -t nfs foo:/bar /nfs
3932
3933Mount the TFTP file system on ’/tftp’:
3934.. code:: c
3935
3936    $ mount -t tftp /tftp
3937
3938To access the TFTP files on server ’10.10.10.10’:
3939.. code:: c
3940
3941    $ cat /tftp/10.10.10.10/test.txt
3942
3943**CONFIGURATION:**
3944
3945.. index:: CONFIGURE_SHELL_NO_COMMAND_MOUNT
3946.. index:: CONFIGURE_SHELL_COMMAND_MOUNT
3947
3948This command is included in the default shell command set.
3949When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MOUNT`` to have this
3950command included.
3951
3952This command can be excluded from the shell command set by
3953defining ``CONFIGURE_SHELL_NO_COMMAND_MOUNT`` when all
3954shell commands have been configured.
3955
3956The mount command includes references to file-system code. If you do not wish
3957to include file-system that you do not use do not define the mount command
3958support for that file-system. The file-system mount command defines are:
3959
3960- msdos - CONFIGURE_SHELL_MOUNT_MSDOS
3961
3962- tftp - CONFIGURE_SHELL_MOUNT_TFTP
3963
3964- ftp - CONFIGURE_SHELL_MOUNT_FTP
3965
3966- nfs - CONFIGURE_SHELL_MOUNT_NFS
3967
3968- rfs - CONFIGURE_SHELL_MOUNT_RFS
3969
3970An example configuration is:
3971.. code:: c
3972
3973    #define CONFIGURE_SHELL_MOUNT_MSDOS
3974    #ifdef RTEMS_NETWORKING
3975    #define CONFIGURE_SHELL_MOUNT_TFTP
3976    #define CONFIGURE_SHELL_MOUNT_FTP
3977    #define CONFIGURE_SHELL_MOUNT_NFS
3978    #define CONFIGURE_SHELL_MOUNT_RFS
3979    #endif
3980
3981**PROGRAMMING INFORMATION:**
3982
3983.. index:: rtems_shell_rtems_main_mount
3984
3985The ``mount`` is implemented by a C language function
3986which has the following prototype:
3987.. code:: c
3988
3989    int rtems_shell_rtems_main_mount(
3990    int    argc,
3991    char \**argv
3992    );
3993
3994The configuration structure for the ``mount`` has the
3995following prototype:
3996.. code:: c
3997
3998    extern rtems_shell_cmd_t rtems_shell_MOUNT_Command;
3999
4000mv - move files
4001---------------
4002.. index:: mv
4003
4004**SYNOPSYS:**
4005
4006.. code:: c
4007
4008    mv \[-fiv] source_file target_file
4009    mv \[-fiv] source_file... target_file
4010
4011**DESCRIPTION:**
4012
4013In its first form, the mv utility renames the file named by the source
4014operand to the destination path named by the target operand.  This
4015form is assumed when the last operand does not name an already
4016existing directory.
4017
4018In its second form, mv moves each file named by a source operand to a
4019destination file in the existing directory named by the directory
4020operand.  The destination path for each operand is the pathname
4021produced by the concatenation of the last operand, a slash, and the
4022final pathname component of the named file.
4023
4024The following options are available:
4025
4026*-f*
4027    Do not prompt for confirmation before overwriting the destination
4028    path.
4029
4030*-i*
4031    Causes mv to write a prompt to standard error before moving a file
4032    that would overwrite an existing file.  If the response from the
4033    standard input begins with the character ’y’, the move is attempted.
4034
4035*-v*
4036    Cause mv to be verbose, showing files as they are processed.
4037
4038The last of any -f or -i options is the one which affects mv’s
4039behavior.
4040
4041It is an error for any of the source operands to specify a nonexistent
4042file or directory.
4043
4044It is an error for the source operand to specify a directory if the
4045target exists and is not a directory.
4046
4047If the destination path does not have a mode which permits writing, mv
4048prompts the user for confirmation as specified for the -i option.
4049
4050Should the *rename* call fail because source and target are on
4051different file systems, ``mv`` will remove the destination file,
4052copy the source file to the destination, and then remove the source.
4053The effect is roughly equivalent to:
4054.. code:: c
4055
4056    rm -f destination_path && \\
4057    cp -PRp source_file destination_path && \\
4058    rm -rf source_file
4059
4060**EXIT STATUS:**
4061
4062The ``mv`` utility exits 0 on success, and >0 if an error occurs.
4063
4064**NOTES:**
4065
4066NONE
4067
4068**EXAMPLES:**
4069
4070.. code:: c
4071
4072    SHLL \[/] mv /dev/console /dev/con1
4073
4074**CONFIGURATION:**
4075
4076.. index:: CONFIGURE_SHELL_NO_COMMAND_MV
4077.. index:: CONFIGURE_SHELL_COMMAND_MV
4078
4079This command is included in the default shell command set.  When
4080building a custom command set, define``CONFIGURE_SHELL_COMMAND_MV`` to have this command included.
4081
4082This command can be excluded from the shell command set by
4083defining ``CONFIGURE_SHELL_NO_COMMAND_MV`` when all
4084shell commands have been configured.
4085
4086**PROGRAMMING INFORMATION:**
4087
4088.. index:: rtems_shell_main_mv
4089
4090The ``mv`` command is implemented by a C language function which
4091has the following prototype:
4092.. code:: c
4093
4094    int rtems_shell_main_mv(
4095    int    argc,
4096    char \**argv
4097    );
4098
4099The configuration structure for the ``mv`` has the
4100following prototype:
4101.. code:: c
4102
4103    extern rtems_shell_cmd_t rtems_shell_MV_Command;
4104
4105**ORIGIN:**
4106
4107The implementation and portions of the documentation for this command
4108are from NetBSD 4.0.
4109
4110pwd - print work directory
4111--------------------------
4112.. index:: pwd
4113
4114**SYNOPSYS:**
4115
4116.. code:: c
4117
4118    pwd
4119
4120**DESCRIPTION:**
4121
4122This command prints the fully qualified filename of the current
4123working directory.
4124
4125**EXIT STATUS:**
4126
4127This command returns 0 on success and non-zero if an error is encountered.
4128
4129**NOTES:**
4130
4131NONE
4132
4133**EXAMPLES:**
4134
4135The following is an example of how to use ``pwd``:
4136.. code:: c
4137
4138    SHLL \[/] $ pwd
4139    /
4140    SHLL \[/] $ cd dev
4141    SHLL \[/dev] $ pwd
4142    /dev
4143
4144**CONFIGURATION:**
4145
4146.. index:: CONFIGURE_SHELL_NO_COMMAND_PWD
4147.. index:: CONFIGURE_SHELL_COMMAND_PWD
4148
4149This command is included in the default shell command set.
4150When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PWD`` to have this
4151command included.
4152
4153This command can be excluded from the shell command set by
4154defining ``CONFIGURE_SHELL_NO_COMMAND_PWD`` when all
4155shell commands have been configured.
4156
4157**PROGRAMMING INFORMATION:**
4158
4159.. index:: rtems_shell_rtems_main_pwd
4160
4161The ``pwd`` is implemented by a C language function
4162which has the following prototype:
4163.. code:: c
4164
4165    int rtems_shell_rtems_main_pwd(
4166    int    argc,
4167    char \**argv
4168    );
4169
4170The configuration structure for the ``pwd`` has the
4171following prototype:
4172.. code:: c
4173
4174    extern rtems_shell_cmd_t rtems_shell_PWD_Command;
4175
4176rmdir - remove empty directories
4177--------------------------------
4178.. index:: rmdir
4179
4180**SYNOPSYS:**
4181
4182.. code:: c
4183
4184    rmdir  \[dir1 .. dirN]
4185
4186**DESCRIPTION:**
4187
4188This command removes the specified set of directories.  If no
4189directories are provided on the command line, no actions are taken.
4190
4191**EXIT STATUS:**
4192
4193This command returns 0 on success and non-zero if an error is encountered.
4194
4195**NOTES:**
4196
4197This command is a implemented using the ``rmdir(2)`` system
4198call and all reasons that call may fail apply to this command.
4199
4200**EXAMPLES:**
4201
4202The following is an example of how to use ``rmdir``:
4203.. code:: c
4204
4205    SHLL \[/] # mkdir joeldir
4206    SHLL \[/] # rmdir joeldir
4207    SHLL \[/] # ls joeldir
4208    joeldir: No such file or directory.
4209
4210**CONFIGURATION:**
4211
4212.. index:: CONFIGURE_SHELL_NO_COMMAND_RMDIR
4213.. index:: CONFIGURE_SHELL_COMMAND_RMDIR
4214
4215This command is included in the default shell command set.
4216When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RMDIR`` to have this
4217command included.
4218
4219This command can be excluded from the shell command set by
4220defining ``CONFIGURE_SHELL_NO_COMMAND_RMDIR`` when all
4221shell commands have been configured.
4222
4223**PROGRAMMING INFORMATION:**
4224
4225.. index:: rtems_shell_rtems_main_rmdir
4226
4227The ``rmdir`` is implemented by a C language function
4228which has the following prototype:
4229.. code:: c
4230
4231    int rtems_shell_rtems_main_rmdir(
4232    int    argc,
4233    char \**argv
4234    );
4235
4236The configuration structure for the ``rmdir`` has the
4237following prototype:
4238.. code:: c
4239
4240    extern rtems_shell_cmd_t rtems_shell_RMDIR_Command;
4241
4242rm - remove files
4243-----------------
4244.. index:: rm
4245
4246**SYNOPSYS:**
4247
4248.. code:: c
4249
4250    rm file1 \[file2 ... fileN]
4251
4252**DESCRIPTION:**
4253
4254This command deletes a name from the filesystem.  If the specified file name
4255was the last link to a file and there are no ``open`` file descriptor
4256references to that file, then it is deleted and the associated space in
4257the file system is made available for subsequent use.
4258
4259If the filename specified was the last link to a file but there
4260are open file descriptor references to it, then the file will
4261remain in existence until the last file descriptor referencing
4262it is closed.
4263
4264**EXIT STATUS:**
4265
4266This command returns 0 on success and non-zero if an error is encountered.
4267
4268**NOTES:**
4269
4270NONE
4271
4272**EXAMPLES:**
4273
4274The following is an example of how to use ``rm``:
4275.. code:: c
4276
4277    SHLL \[/] # cp /etc/passwd tmpfile
4278    SHLL \[/] # cat tmpfile
4279    root:\*:0:0:root::/:/bin/sh
4280    rtems:\*:1:1:RTEMS Application::/:/bin/sh
4281    tty:!:2:2:tty owner::/:/bin/false
4282    SHLL \[/] # rm tmpfile
4283    SHLL \[/] # cat tmpfile
4284    cat: tmpfile: No such file or directory
4285
4286**CONFIGURATION:**
4287
4288.. index:: CONFIGURE_SHELL_NO_COMMAND_RM
4289.. index:: CONFIGURE_SHELL_COMMAND_RM
4290
4291This command is included in the default shell command set.
4292When building a custom command set, define``CONFIGURE_SHELL_COMMAND_RM`` to have this
4293command included.
4294
4295This command can be excluded from the shell command set by
4296defining ``CONFIGURE_SHELL_NO_COMMAND_RM`` when all
4297shell commands have been configured.
4298
4299**PROGRAMMING INFORMATION:**
4300
4301.. index:: rtems_shell_main_rm
4302
4303The ``rm`` is implemented by a C language function
4304which has the following prototype:
4305.. code:: c
4306
4307    int rtems_shell_main_rm(
4308    int    argc,
4309    char \**argv
4310    );
4311
4312The configuration structure for the ``rm`` has the
4313following prototype:
4314.. code:: c
4315
4316    extern rtems_shell_cmd_t rtems_shell_RM_Command;
4317
4318umask - set file mode creation mask
4319-----------------------------------
4320.. index:: umask
4321
4322**SYNOPSYS:**
4323
4324.. code:: c
4325
4326    umask \[new_umask]
4327
4328**DESCRIPTION:**
4329
4330This command sets the user file creation mask to ``new_umask``.  The
4331argument ``new_umask`` may be octal, hexadecimal, or decimal.
4332
4333**EXIT STATUS:**
4334
4335This command returns 0 on success and non-zero if an error is encountered.
4336
4337**NOTES:**
4338
4339This command does not currently support symbolic mode masks.
4340
4341**EXAMPLES:**
4342
4343The following is an example of how to use ``umask``:
4344.. code:: c
4345
4346    SHLL \[/] $ umask
4347    022
4348    SHLL \[/] $ umask 0666
4349    0666
4350    SHLL \[/] $ umask
4351    0666
4352
4353**CONFIGURATION:**
4354
4355.. index:: CONFIGURE_SHELL_NO_COMMAND_UMASK
4356.. index:: CONFIGURE_SHELL_COMMAND_UMASK
4357
4358This command is included in the default shell command set.
4359When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UMASK`` to have this
4360command included.
4361
4362This command can be excluded from the shell command set by
4363defining ``CONFIGURE_SHELL_NO_COMMAND_UMASK`` when all
4364shell commands have been configured.
4365
4366**PROGRAMMING INFORMATION:**
4367
4368.. index:: rtems_shell_rtems_main_umask
4369
4370The ``umask`` is implemented by a C language function
4371which has the following prototype:
4372.. code:: c
4373
4374    int rtems_shell_rtems_main_umask(
4375    int    argc,
4376    char \**argv
4377    );
4378
4379The configuration structure for the ``umask`` has the
4380following prototype:
4381.. code:: c
4382
4383    extern rtems_shell_cmd_t rtems_shell_UMASK_Command;
4384
4385unmount - unmount disk
4386----------------------
4387.. index:: unmount
4388
4389**SYNOPSYS:**
4390
4391.. code:: c
4392
4393    unmount path
4394
4395**DESCRIPTION:**
4396
4397This command unmounts the device at the specified ``path``.
4398
4399**EXIT STATUS:**
4400
4401This command returns 0 on success and non-zero if an error is encountered.
4402
4403**NOTES:**
4404
4405TBD - Surely there must be some warnings to go here.
4406
4407**EXAMPLES:**
4408
4409The following is an example of how to use ``unmount``:
4410.. code:: c
4411
4412    EXAMPLE_TBD
4413
4414**CONFIGURATION:**
4415
4416.. index:: CONFIGURE_SHELL_NO_COMMAND_UNMOUNT
4417.. index:: CONFIGURE_SHELL_COMMAND_UNMOUNT
4418
4419This command is included in the default shell command set.
4420When building a custom command set, define``CONFIGURE_SHELL_COMMAND_UNMOUNT`` to have this
4421command included.
4422
4423This command can be excluded from the shell command set by
4424defining ``CONFIGURE_SHELL_NO_COMMAND_UNMOUNT`` when all
4425shell commands have been configured.
4426
4427**PROGRAMMING INFORMATION:**
4428
4429.. index:: rtems_shell_rtems_main_unmount
4430
4431The ``unmount`` is implemented by a C language function
4432which has the following prototype:
4433.. code:: c
4434
4435    int rtems_shell_rtems_main_unmount(
4436    int    argc,
4437    char \**argv
4438    );
4439
4440The configuration structure for the ``unmount`` has the
4441following prototype:
4442.. code:: c
4443
4444    extern rtems_shell_cmd_t rtems_shell_UNMOUNT_Command;
4445
4446.. COMMENT: COPYRIGHT (c) 1988-2012.
4447
4448.. COMMENT: On-Line Applications Research Corporation (OAR).
4449
4450.. COMMENT: All rights reserved.
4451
4452Memory Commands
4453###############
4454
4455Introduction
4456============
4457
4458The RTEMS shell has the following memory commands:
4459
4460- ``mdump`` - Display contents of memory
4461
4462- ``wdump`` - Display contents of memory (word)
4463
4464- ``ldump`` - Display contents of memory (longword)
4465
4466- ``medit`` - Modify contents of memory
4467
4468- ``mfill`` - File memory with pattern
4469
4470- ``mmove`` - Move contents of memory
4471
4472- ``malloc`` - Obtain information on C Program Heap
4473
4474Commands
4475========
4476
4477This section details the Memory Commands available.  A
4478subsection is dedicated to each of the commands and
4479describes the behavior and configuration of that
4480command as well as providing an example usage.
4481
4482mdump - display contents of memory
4483----------------------------------
4484.. index:: mdump
4485
4486**SYNOPSYS:**
4487
4488.. code:: c
4489
4490    mdump \[address \[length \[size]]]
4491
4492**DESCRIPTION:**
4493
4494This command displays the contents of memory at the ``address``
4495and ``length`` in ``size`` byte units specified on the command line.
4496
4497When ``size`` is not provided, it defaults to ``1`` byte units.
4498Values of ``1``, ``2``, and ``4`` are valid; all others will
4499cause an error to be reported.
4500
4501When ``length`` is not provided, it defaults to ``320`` which
4502is twenty lines of output with sixteen bytes of output per line.
4503
4504When ``address`` is not provided, it defaults to ``0x00000000``.
4505
4506**EXIT STATUS:**
4507
4508This command always returns 0 to indicate success.
4509
4510**NOTES:**
4511
4512Dumping memory from a non-existent address may result in an unrecoverable
4513program fault.
4514
4515**EXAMPLES:**
4516
4517The following is an example of how to use ``mdump``:
4518.. code:: c
4519
4520    SHLL \[/] $ mdump 0x10000 32
4521    0x0001000000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
4522    0x0001001000 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................
4523    SHLL \[/] $ mdump 0x02000000 32
4524    0x02000000A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
4525    0x02000010A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
4526    SHLL \[/] $ mdump 0x02001000 32
4527    0x0200100003 00 80 00 82 10 60 00-81 98 40 00 83 48 00 00 ......`.....H..
4528    0x0200101084 00 60 01 84 08 A0 07-86 10 20 01 87 28 C0 02 ..`....... ..(..
4529
4530**CONFIGURATION:**
4531
4532.. index:: CONFIGURE_SHELL_NO_COMMAND_MDUMP
4533.. index:: CONFIGURE_SHELL_COMMAND_MDUMP
4534
4535This command is included in the default shell command set.
4536When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MDUMP`` to have this
4537command included.
4538
4539This command can be excluded from the shell command set by
4540defining ``CONFIGURE_SHELL_NO_COMMAND_MDUMP`` when all
4541shell commands have been configured.
4542
4543**PROGRAMMING INFORMATION:**
4544
4545.. index:: rtems_shell_rtems_main_mdump
4546
4547The ``mdump`` is implemented by a C language function
4548which has the following prototype:
4549.. code:: c
4550
4551    int rtems_shell_rtems_main_mdump(
4552    int    argc,
4553    char \**argv
4554    );
4555
4556The configuration structure for the ``mdump`` has the
4557following prototype:
4558.. code:: c
4559
4560    extern rtems_shell_cmd_t rtems_shell_MDUMP_Command;
4561
4562wdump - display contents of memory (word)
4563-----------------------------------------
4564.. index:: wdump
4565
4566**SYNOPSYS:**
4567
4568.. code:: c
4569
4570    wdump \[address \[length]]
4571
4572**DESCRIPTION:**
4573
4574This command displays the contents of memory at the ``address``
4575and ``length`` in bytes specified on the command line.
4576
4577This command is equivalent to ``mdump address length 2``.
4578
4579When ``length`` is not provided, it defaults to ``320`` which
4580is twenty lines of output with eight words of output per line.
4581
4582When ``address`` is not provided, it defaults to ``0x00000000``.
4583
4584**EXIT STATUS:**
4585
4586This command always returns 0 to indicate success.
4587
4588**NOTES:**
4589
4590Dumping memory from a non-existent address may result in an unrecoverable
4591program fault.
4592
4593**EXAMPLES:**
4594
4595The following is an example of how to use ``wdump``:
4596.. code:: c
4597
4598    SHLL \[/] $ wdump 0x02010000 32
4599    0x02010000 0201 08D8 0201 08C0-0201 08AC 0201 0874 ...............t
4600    0x02010010 0201 0894 0201 0718-0201 0640 0201 0798 ...............
4601
4602**CONFIGURATION:**
4603
4604.. index:: CONFIGURE_SHELL_NO_COMMAND_WDUMP
4605.. index:: CONFIGURE_SHELL_COMMAND_WDUMP
4606
4607This command is included in the default shell command set.
4608When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WDUMP`` to have this
4609command included.
4610
4611This command can be excluded from the shell command set by
4612defining ``CONFIGURE_SHELL_NO_COMMAND_WDUMP`` when all
4613shell commands have been configured.
4614
4615**PROGRAMMING INFORMATION:**
4616
4617.. index:: rtems_shell_rtems_main_wdump
4618
4619The ``wdump`` is implemented by a C language function
4620which has the following prototype:
4621.. code:: c
4622
4623    int rtems_shell_rtems_main_wdump(
4624    int    argc,
4625    char \**argv
4626    );
4627
4628The configuration structure for the ``wdump`` has the
4629following prototype:
4630.. code:: c
4631
4632    extern rtems_shell_cmd_t rtems_shell_WDUMP_Command;
4633
4634ldump - display contents of memory (longword)
4635---------------------------------------------
4636.. index:: ldump
4637
4638**SYNOPSYS:**
4639
4640.. code:: c
4641
4642    ldump \[address \[length]]
4643
4644**DESCRIPTION:**
4645
4646This command displays the contents of memory at the ``address``
4647and ``length`` in bytes specified on the command line.
4648
4649This command is equivalent to ``mdump address length 4``.
4650
4651When ``length`` is not provided, it defaults to ``320`` which
4652is twenty lines of output with four longwords of output per line.
4653
4654When ``address`` is not provided, it defaults to ``0x00000000``.
4655
4656**EXIT STATUS:**
4657
4658This command always returns 0 to indicate success.
4659
4660**NOTES:**
4661
4662Dumping memory from a non-existent address may result in an unrecoverable
4663program fault.
4664
4665**EXAMPLES:**
4666
4667The following is an example of how to use ``ldump``:
4668.. code:: c
4669
4670    SHLL \[/] $ ldump 0x02010000 32
4671    0x02010000 020108D8 020108C0-020108AC 02010874 ...............t
4672    0x02010010 020 0894 02010718-02010640 02010798 ...............
4673
4674**CONFIGURATION:**
4675
4676.. index:: CONFIGURE_SHELL_NO_COMMAND_LDUMP
4677.. index:: CONFIGURE_SHELL_COMMAND_LDUMP
4678
4679This command is included in the default shell command set.
4680When building a custom command set, define``CONFIGURE_SHELL_COMMAND_LDUMP`` to have this
4681command included.
4682
4683This command can be excluded from the shell command set by
4684defining ``CONFIGURE_SHELL_NO_COMMAND_LDUMP`` when all
4685shell commands have been configured.
4686
4687**PROGRAMMING INFORMATION:**
4688
4689.. index:: rtems_shell_rtems_main_ldump
4690
4691The ``ldump`` is implemented by a C language function
4692which has the following prototype:
4693.. code:: c
4694
4695    int rtems_shell_rtems_main_ldump(
4696    int    argc,
4697    char \**argv
4698    );
4699
4700The configuration structure for the ``ldump`` has the
4701following prototype:
4702.. code:: c
4703
4704    extern rtems_shell_cmd_t rtems_shell_LDUMP_Command;
4705
4706medit - modify contents of memory
4707---------------------------------
4708.. index:: medit
4709
4710**SYNOPSYS:**
4711
4712.. code:: c
4713
4714    medit address value1 \[value2 ... valueN]
4715
4716**DESCRIPTION:**
4717
4718This command is used to modify the contents of the memory starting
4719at ``address`` using the octets specified by the parameters``value1`` through ``valueN``.
4720
4721**EXIT STATUS:**
4722
4723This command returns 0 on success and non-zero if an error is encountered.
4724
4725**NOTES:**
4726
4727Dumping memory from a non-existent address may result in an unrecoverable
4728program fault.
4729
4730**EXAMPLES:**
4731
4732The following is an example of how to use ``medit``:
4733.. code:: c
4734
4735    SHLL \[/] $ mdump 0x02000000 32
4736    0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
4737    0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
4738    SHLL \[/] $  medit 0x02000000 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09
4739    SHLL \[/] $ mdump 0x02000000 32
4740    0x02000000 01 02 03 04 05 06 07 08-09 00 22 BC A6 10 21 00 .........."...!.
4741    0x02000010 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 01 .H..)..3.."...!.
4742
4743**CONFIGURATION:**
4744
4745.. index:: CONFIGURE_SHELL_NO_COMMAND_MEDIT
4746.. index:: CONFIGURE_SHELL_COMMAND_MEDIT
4747
4748This command is included in the default shell command set.
4749When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MEDIT`` to have this
4750command included.
4751
4752This command can be excluded from the shell command set by
4753defining ``CONFIGURE_SHELL_NO_COMMAND_MEDIT`` when all
4754shell commands have been configured.
4755
4756**PROGRAMMING INFORMATION:**
4757
4758.. index:: rtems_shell_rtems_main_medit
4759
4760The ``medit`` is implemented by a C language function
4761which has the following prototype:
4762.. code:: c
4763
4764    int rtems_shell_rtems_main_medit(
4765    int    argc,
4766    char \**argv
4767    );
4768
4769The configuration structure for the ``medit`` has the
4770following prototype:
4771.. code:: c
4772
4773    extern rtems_shell_cmd_t rtems_shell_MEDIT_Command;
4774
4775mfill - file memory with pattern
4776--------------------------------
4777.. index:: mfill
4778
4779**SYNOPSYS:**
4780
4781.. code:: c
4782
4783    mfill address length value
4784
4785**DESCRIPTION:**
4786
4787This command is used to fill the memory starting at ``address``
4788for the specified ``length`` in octets when the specified at``value``.
4789
4790**EXIT STATUS:**
4791
4792This command returns 0 on success and non-zero if an error is encountered.
4793
4794**NOTES:**
4795
4796Filling a non-existent address range may result in an unrecoverable
4797program fault.  Similarly overwriting interrupt vector tables, code
4798space or critical data areas can be fatal as shown in the example.
4799
4800**EXAMPLES:**
4801
4802In this example, the address used (``0x23d89a0``) as the base
4803address of the filled area is the end of the stack for the
4804Idle thread.  This address was determined manually using gdb and
4805is very specific to this application and BSP.  The first command
4806in this example is an ``mdump`` to display the initial contents
4807of this memory.  We see that the first 8 bytes are 0xA5 which is
4808the pattern used as a guard by the Stack Checker.  On
4809the first context switch after the pattern is overwritten
4810by the  ``mfill`` command, the Stack Checker detect the pattern
4811has been corrupted and generates a fatal error.
4812.. code:: c
4813
4814    SHLL \[/] $ mdump 0x23d89a0 16
4815    0x023D89A0 A5 A5 A5 A5 A5 A5 A5 A5-FE ED F0 0D 0B AD 0D 06 ................
4816    SHLL \[/] $ mfill 0x23d89a0 13 0x5a
4817    SHLL \[/] $ BLOWN STACK!!! Offending task(0x23D4418): id=0x09010001; name=0x0203D908
4818    stack covers range 0x23D89A0 - 0x23D99AF (4112 bytes)
4819    Damaged pattern begins at 0x023D89A8 and is 16 bytes long
4820
4821**CONFIGURATION:**
4822
4823.. index:: CONFIGURE_SHELL_NO_COMMAND_MFILL
4824.. index:: CONFIGURE_SHELL_COMMAND_MFILL
4825
4826This command is included in the default shell command set.
4827When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MFILL`` to have this
4828command included.
4829
4830This command can be excluded from the shell command set by
4831defining ``CONFIGURE_SHELL_NO_COMMAND_MFILL`` when all
4832shell commands have been configured.
4833
4834**PROGRAMMING INFORMATION:**
4835
4836.. index:: rtems_shell_rtems_main_mfill
4837
4838The ``mfill`` is implemented by a C language function
4839which has the following prototype:
4840.. code:: c
4841
4842    int rtems_shell_rtems_main_mfill(
4843    int    argc,
4844    char \**argv
4845    );
4846
4847The configuration structure for the ``mfill`` has the
4848following prototype:
4849.. code:: c
4850
4851    extern rtems_shell_cmd_t rtems_shell_MFILL_Command;
4852
4853mmove - move contents of memory
4854-------------------------------
4855.. index:: mmove
4856
4857**SYNOPSYS:**
4858
4859.. code:: c
4860
4861    mmove dst src length
4862
4863**DESCRIPTION:**
4864
4865This command is used to copy the contents of the memory
4866starting at ``src`` to the memory located at ``dst``
4867for the specified ``length`` in octets.
4868
4869**EXIT STATUS:**
4870
4871This command returns 0 on success and non-zero if an error is encountered.
4872
4873**NOTES:**
4874
4875NONE
4876
4877**EXAMPLES:**
4878
4879The following is an example of how to use ``mmove``:
4880.. code:: c
4881
4882    SHLL \[/] $ mdump 0x023d99a0 16
4883    0x023D99A0 A5 A5 A5 A5 A5 A5 A5 A5-A5 A5 A5 A5 A5 A5 A5 A5 ................
4884    SHLL \[/] $ mdump 0x02000000 16
4885    0x02000000 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 10 21 00 .H..)..3.."...!.
4886    SHLL \[/] $ mmove 0x023d99a0 0x02000000 13
4887    SHLL \[/] $ mdump 0x023d99a0 16
4888    0x023D99A0 A1 48 00 00 29 00 80 33-81 C5 22 BC A6 A5 A5 A5 .H..)..3..".....
4889
4890**CONFIGURATION:**
4891
4892.. index:: CONFIGURE_SHELL_NO_COMMAND_MMOVE
4893.. index:: CONFIGURE_SHELL_COMMAND_MMOVE
4894
4895This command is included in the default shell command set.
4896When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MMOVE`` to have this
4897command included.
4898
4899This command can be excluded from the shell command set by
4900defining ``CONFIGURE_SHELL_NO_COMMAND_MMOVE`` when all
4901shell commands have been configured.
4902
4903**PROGRAMMING INFORMATION:**
4904
4905.. index:: rtems_shell_rtems_main_mmove
4906
4907The ``mmove`` is implemented by a C language function
4908which has the following prototype:
4909.. code:: c
4910
4911    int rtems_shell_rtems_main_mmove(
4912    int    argc,
4913    char \**argv
4914    );
4915
4916The configuration structure for the ``mmove`` has the
4917following prototype:
4918.. code:: c
4919
4920    extern rtems_shell_cmd_t rtems_shell_MMOVE_Command;
4921
4922malloc - obtain information on C program heap
4923---------------------------------------------
4924.. index:: malloc
4925
4926**SYNOPSYS:**
4927
4928.. code:: c
4929
4930    malloc \[walk]
4931
4932**DESCRIPTION:**
4933
4934This command prints information about the current state of the C Program Heap
4935used by the ``malloc()`` family of calls if no or invalid options are passed
4936to the command.  This includes the following information:
4937
4938- Number of free blocks
4939
4940- Largest free block
4941
4942- Total bytes free
4943
4944- Number of used blocks
4945
4946- Largest used block
4947
4948- Total bytes used
4949
4950- Size of the allocatable area in bytes
4951
4952- Minimum free size ever in bytes
4953
4954- Maximum number of free blocks ever
4955
4956- Maximum number of blocks searched ever
4957
4958- Lifetime number of bytes allocated
4959
4960- Lifetime number of bytes freed
4961
4962- Total number of searches
4963
4964- Total number of successful allocations
4965
4966- Total number of failed allocations
4967
4968- Total number of successful frees
4969
4970- Total number of successful resizes
4971
4972When the subcommand ``walk`` is specified, then a heap walk will be
4973performed and information about each block is printed out.
4974
4975**EXIT STATUS:**
4976
4977This command returns 0 on success and non-zero if an error is encountered.
4978
4979**NOTES:**
4980
4981NONE
4982
4983**EXAMPLES:**
4984
4985The following is an example of how to use the ``malloc`` command.
4986.. code:: c
4987
4988    SHLL \[/] $ malloc
4989    C Program Heap and RTEMS Workspace are the same.
4990    Number of free blocks:                               2
4991    Largest free block:                          266207504
4992    Total bytes free:                            266208392
4993    Number of used blocks:                             167
4994    Largest used block:                              16392
4995    Total bytes used:                                83536
4996    Size of the allocatable area in bytes:       266291928
4997    Minimum free size ever in bytes:             266207360
4998    Maximum number of free blocks ever:                  6
4999    Maximum number of blocks searched ever:              5
5000    Lifetime number of bytes allocated:              91760
5001    Lifetime number of bytes freed:                   8224
5002    Total number of searches:                          234
5003    Total number of successful allocations:            186
5004    Total number of failed allocations:                  0
5005    Total number of successful frees:                   19
5006    Total number of successful resizes:                  0
5007    SHLL \[/] $ malloc walk
5008    malloc walk
5009    PASS[0]: page size 8, min block size 48
5010    area begin 0x00210210, area end 0x0FFFC000
5011    first block 0x00210214, last block 0x0FFFBFDC
5012    first free 0x00228084, last free 0x00228354
5013    PASS[0]: block 0x00210214: size 88
5014    ...
5015    PASS[0]: block 0x00220154: size 144
5016    PASS[0]: block 0x002201E4: size 168, prev 0x002205BC, next 0x00228354 (= last free)
5017    PASS[0]: block 0x0022028C: size 168, prev_size 168
5018    ...
5019    PASS[0]: block 0x00226E7C: size 4136
5020    PASS[0]: block 0x00227EA4: size 408, prev 0x00228084 (= first free), next 0x00226CE4
5021    PASS[0]: block 0x0022803C: size 72, prev_size 408
5022    PASS[0]: block 0x00228084: size 648, prev 0x0020F75C (= head), next 0x00227EA4
5023    PASS[0]: block 0x0022830C: size 72, prev_size 648
5024    PASS[0]: block 0x00228354: size 266157192, prev 0x002201E4, next 0x0020F75C (= tail)
5025    PASS[0]: block 0x0FFFBFDC: size 4028711480, prev_size 266157192
5026
5027**CONFIGURATION:**
5028
5029.. index:: CONFIGURE_SHELL_NO_COMMAND_MALLOC
5030.. index:: CONFIGURE_SHELL_COMMAND_MALLOC
5031
5032This command is included in the default shell command set.
5033When building a custom command set, define``CONFIGURE_SHELL_COMMAND_MALLOC`` to have this
5034command included.
5035
5036This command can be excluded from the shell command set by
5037defining ``CONFIGURE_SHELL_NO_COMMAND_MALLOC`` when all
5038shell commands have been configured.
5039
5040**PROGRAMMING INFORMATION:**
5041
5042.. index:: rtems_shell_rtems_main_malloc
5043
5044The ``malloc`` is implemented by a C language function
5045which has the following prototype:
5046.. code:: c
5047
5048    int rtems_shell_rtems_main_malloc(
5049    int    argc,
5050    char \**argv
5051    );
5052
5053The configuration structure for the ``malloc`` has the
5054following prototype:
5055.. code:: c
5056
5057    extern rtems_shell_cmd_t rtems_shell_MALLOC_Command;
5058
5059.. COMMENT: COPYRIGHT (c) 1988-2008.
5060
5061.. COMMENT: On-Line Applications Research Corporation (OAR).
5062
5063.. COMMENT: All rights reserved.
5064
5065RTEMS Specific Commands
5066#######################
5067
5068Introduction
5069============
5070
5071The RTEMS shell has the following rtems commands:
5072
5073- ``shutdown`` - Shutdown the system
5074
5075- ``cpuuse`` - print or reset per thread cpu usage
5076
5077- ``stackuse`` - print per thread stack usage
5078
5079- ``perioduse`` - print or reset per period usage
5080
5081- ``profreport`` - print a profiling report
5082
5083- ``wkspace`` - Display information on Executive Workspace
5084
5085- ``config`` - Show the system configuration.
5086
5087- ``itask`` - List init tasks for the system
5088
5089- ``extension`` - Display information about extensions
5090
5091- ``task`` - Display information about tasks
5092
5093- ``queue`` - Display information about message queues
5094
5095- ``sema`` - display information about semaphores
5096
5097- ``region`` - display information about regions
5098
5099- ``part`` - display information about partitions
5100
5101- ``object`` - Display information about RTEMS objects
5102
5103- ``driver`` - Display the RTEMS device driver table
5104
5105- ``dname`` - Displays information about named drivers
5106
5107- ``pthread`` - Displays information about POSIX threads
5108
5109Commands
5110========
5111
5112This section details the RTEMS Specific Commands available.  A
5113subsection is dedicated to each of the commands and
5114describes the behavior and configuration of that
5115command as well as providing an example usage.
5116
5117shutdown - Shutdown the system
5118------------------------------
5119.. index:: shutdown
5120
5121**SYNOPSYS:**
5122
5123.. code:: c
5124
5125    shutdown
5126
5127**DESCRIPTION:**
5128
5129This command is used to shutdown the RTEMS application.
5130
5131**EXIT STATUS:**
5132
5133This command does not return.
5134
5135**NOTES:**
5136
5137**EXAMPLES:**
5138
5139The following is an example of how to use ``shutdown``:
5140.. code:: c
5141
5142    SHLL \[/] $ shutdown
5143    System shutting down at user request
5144
5145The user will not see another prompt and the system will
5146shutdown.
5147
5148**CONFIGURATION:**
5149
5150.. index:: CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN
5151.. index:: CONFIGURE_SHELL_COMMAND_SHUTDOWN
5152
5153This command is included in the default shell command set.
5154When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SHUTDOWN`` to have this
5155command included.
5156
5157This command can be excluded from the shell command set by
5158defining ``CONFIGURE_SHELL_NO_COMMAND_SHUTDOWN`` when all
5159shell commands have been configured.
5160
5161**PROGRAMMING INFORMATION:**
5162
5163The configuration structure for the ``shutdown`` has the
5164following prototype:
5165.. code:: c
5166
5167    extern rtems_shell_cmd_t rtems_shell_SHUTDOWN_Command;
5168
5169cpuuse - print or reset per thread cpu usage
5170--------------------------------------------
5171.. index:: cpuuse
5172
5173**SYNOPSYS:**
5174
5175.. code:: c
5176
5177    cpuuse \[-r]
5178
5179**DESCRIPTION:**
5180
5181This command may be used to print a report on the per thread
5182cpu usage or to reset the per thread CPU usage statistics. When
5183invoked with the ``-r`` option, the CPU usage statistics
5184are reset.
5185
5186**EXIT STATUS:**
5187
5188This command returns 0 on success and non-zero if an error is encountered.
5189
5190**NOTES:**
5191
5192The granularity of the timing information reported is dependent
5193upon the BSP and the manner in which RTEMS was built.  In the
5194default RTEMS configuration, if the BSP supports nanosecond
5195granularity timestamps, then the information reported will be
5196highly accurate. Otherwise, the accuracy of the information
5197reported is limited by the clock tick quantum.
5198
5199**EXAMPLES:**
5200
5201The following is an example of how to use ``cpuuse``:
5202.. code:: c
5203
5204    SHLL \[/] $ cpuuse
5205    CPU Usage by thread
5206    ID            NAME         SECONDS   PERCENT
5207    0x09010001   IDLE            49.745393   98.953
5208    0x0a010001   UI1              0.000000    0.000
5209    0x0a010002   SHLL             0.525928    1.046
5210    Time since last CPU Usage reset 50.271321 seconds
5211    SHLL \[/] $ cpuuse -r
5212    Resetting CPU Usage information
5213    SHLL \[/] $ cpuuse
5214    CPU Usage by thread
5215    ID            NAME         SECONDS   PERCENT
5216    0x09010001   IDLE             0.000000    0.000
5217    0x0a010001   UI1              0.000000    0.000
5218    0x0a010002   SHLL             0.003092  100.000
5219    Time since last CPU Usage reset 0.003092 seconds
5220
5221In the above example, the system had set idle for nearly
5222a minute when the first report was generated.  The``cpuuse -r`` and ``cpuuse`` commands were pasted
5223from another window so were executed with no gap between.
5224In the second report, only the ``shell`` thread has
5225run since the CPU Usage was reset.  It has consumed
5226approximately 3.092 milliseconds of CPU time processing
5227the two commands and generating the output.
5228
5229**CONFIGURATION:**
5230
5231.. index:: CONFIGURE_SHELL_NO_COMMAND_CPUUSE
5232.. index:: CONFIGURE_SHELL_COMMAND_CPUUSE
5233
5234This command is included in the default shell command set.
5235When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CPUUSE`` to have this
5236command included.
5237
5238This command can be excluded from the shell command set by
5239defining ``CONFIGURE_SHELL_NO_COMMAND_CPUUSE`` when all
5240shell commands have been configured.
5241
5242**PROGRAMMING INFORMATION:**
5243
5244.. index:: rtems_shell_rtems_main_cpuuse
5245
5246The ``cpuuse`` is implemented by a C language function
5247which has the following prototype:
5248.. code:: c
5249
5250    int rtems_shell_rtems_main_cpuuse(
5251    int    argc,
5252    char \**argv
5253    );
5254
5255The configuration structure for the ``cpuuse`` has the
5256following prototype:
5257.. code:: c
5258
5259    extern rtems_shell_cmd_t rtems_shell_CPUUSE_Command;
5260
5261stackuse - print per thread stack usage
5262---------------------------------------
5263.. index:: stackuse
5264
5265**SYNOPSYS:**
5266
5267.. code:: c
5268
5269    stackuse
5270
5271**DESCRIPTION:**
5272
5273This command prints a Stack Usage Report for all of the tasks
5274and threads in the system.  On systems which support it, the
5275usage of the interrupt stack is also included in the report.
5276
5277**EXIT STATUS:**
5278
5279This command always succeeds and returns 0.
5280
5281**NOTES:**
5282
5283The ``CONFIGURE_STACK_CHECKER_ENABLED`` ``confdefs.h`` constant
5284must be defined when the application is configured for this
5285command to have any information to report.
5286
5287**EXAMPLES:**
5288
5289The following is an example of how to use ``stackuse``:
5290.. code:: c
5291
5292    SHLL \[/] $ stackuse
5293    Stack usage by thread
5294    ID      NAME    LOW          HIGH     CURRENT     AVAILABLE     USED
5295    0x09010001  IDLE 0x023d89a0 - 0x023d99af 0x023d9760      4096        608
5296    0x0a010001  UI1  0x023d9f30 - 0x023daf3f 0x023dad18      4096       1804
5297    0x0a010002  SHLL 0x023db4c0 - 0x023df4cf 0x023de9d0     16384       5116
5298    0xffffffff  INTR 0x023d2760 - 0x023d375f 0x00000000      4080        316
5299
5300**CONFIGURATION:**
5301
5302.. index:: CONFIGURE_SHELL_NO_COMMAND_STACKUSE
5303.. index:: CONFIGURE_SHELL_COMMAND_STACKUSE
5304
5305This command is included in the default shell command set.
5306When building a custom command set, define``CONFIGURE_SHELL_COMMAND_STACKUSE`` to have this
5307command included.
5308
5309This command can be excluded from the shell command set by
5310defining ``CONFIGURE_SHELL_NO_COMMAND_STACKUSE`` when all
5311shell commands have been configured.
5312
5313**PROGRAMMING INFORMATION:**
5314
5315.. index:: rtems_shell_rtems_main_stackuse
5316
5317The ``stackuse`` is implemented by a C language function
5318which has the following prototype:
5319.. code:: c
5320
5321    int rtems_shell_rtems_main_stackuse(
5322    int    argc,
5323    char \**argv
5324    );
5325
5326The configuration structure for the ``stackuse`` has the
5327following prototype:
5328.. code:: c
5329
5330    extern rtems_shell_cmd_t rtems_shell_STACKUSE_Command;
5331
5332perioduse - print or reset per period usage
5333-------------------------------------------
5334.. index:: perioduse
5335
5336**SYNOPSYS:**
5337
5338.. code:: c
5339
5340    perioduse \[-r]
5341
5342**DESCRIPTION:**
5343
5344This command may be used to print a statistics report on the rate
5345monotonic periods in the application or to reset the rate monotonic
5346period usage statistics. When invoked with the ``-r`` option, the
5347usage statistics are reset.
5348
5349**EXIT STATUS:**
5350
5351This command returns 0 on success and non-zero if an error is encountered.
5352
5353**NOTES:**
5354
5355The granularity of the timing information reported is dependent
5356upon the BSP and the manner in which RTEMS was built.  In the
5357default RTEMS configuration, if the BSP supports nanosecond
5358granularity timestamps, then the information reported will be
5359highly accurate. Otherwise, the accuracy of the information
5360reported is limited by the clock tick quantum.
5361
5362**EXAMPLES:**
5363
5364The following is an example of how to use ``perioduse``:
5365.. code:: c
5366
5367    SHLL \[/] $ perioduse
5368    Period information by period
5369    --- CPU times are in seconds ---
5370    --- Wall times are in seconds ---
5371    ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
5372    MIN/MAX/AVG                MIN/MAX/AVG
5373    0x42010001 TA1    502      0 0:000039/0:042650/0:004158 0:000039/0:020118/0:002848
5374    0x42010002 TA2    502      0 0:000041/0:042657/0:004309 0:000041/0:020116/0:002848
5375    0x42010003 TA3    501      0 0:000041/0:041564/0:003653 0:000041/0:020003/0:002814
5376    0x42010004 TA4    501      0 0:000043/0:044075/0:004911 0:000043/0:020004/0:002814
5377    0x42010005 TA5     10      0 0:000065/0:005413/0:002739 0:000065/1:000457/0:041058
5378    MIN/MAX/AVG                MIN/MAX/AVG
5379    SHLL \[/] $ perioduse -r
5380    Resetting Period Usage information
5381    SHLL \[/] $ perioduse
5382    --- CPU times are in seconds ---
5383    --- Wall times are in seconds ---
5384    ID     OWNER COUNT MISSED          CPU TIME                  WALL TIME
5385    MIN/MAX/AVG                MIN/MAX/AVG
5386    0x42010001 TA1      0      0
5387    0x42010002 TA2      0      0
5388    0x42010003 TA3      0      0
5389    0x42010004 TA4      0      0
5390    0x42010005 TA5      0      0
5391
5392**CONFIGURATION:**
5393
5394.. index:: CONFIGURE_SHELL_NO_COMMAND_PERIODUSE
5395.. index:: CONFIGURE_SHELL_COMMAND_PERIODUSE
5396
5397This command is included in the default shell command set.
5398When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PERIODUSE`` to have this
5399command included.
5400
5401This command can be excluded from the shell command set by
5402defining ``CONFIGURE_SHELL_NO_COMMAND_PERIODUSE`` when all
5403shell commands have been configured.
5404
5405**PROGRAMMING INFORMATION:**
5406
5407.. index:: rtems_shell_rtems_main_perioduse
5408
5409The ``perioduse`` is implemented by a C language function
5410which has the following prototype:
5411.. code:: c
5412
5413    int rtems_shell_rtems_main_perioduse(
5414    int    argc,
5415    char \**argv
5416    );
5417
5418The configuration structure for the ``perioduse`` has the
5419following prototype:
5420.. code:: c
5421
5422    extern rtems_shell_cmd_t rtems_shell_PERIODUSE_Command;
5423
5424profreport - print a profiling report
5425-------------------------------------
5426.. index:: profreport
5427
5428**SYNOPSYS:**
5429
5430.. code:: c
5431
5432    profreport
5433
5434**DESCRIPTION:**
5435
5436This command may be used to print a profiling report.
5437
5438**EXIT STATUS:**
5439
5440This command returns 0.
5441
5442**NOTES:**
5443
5444Profiling must be enabled at build configuration time to get profiling
5445information.
5446
5447**EXAMPLES:**
5448
5449The following is an example of how to use ``profreport``:
5450.. code:: c
5451
5452    SHLL \[/] $ profreport
5453    <ProfilingReport name="Shell">
5454    <PerCPUProfilingReport processorIndex="0">
5455    <MaxThreadDispatchDisabledTime unit="ns">10447</MaxThreadDispatchDisabledTime>
5456    <MeanThreadDispatchDisabledTime unit="ns">2</MeanThreadDispatchDisabledTime>
5457    <TotalThreadDispatchDisabledTime unit="ns">195926627</TotalThreadDispatchDisabledTime>
5458    <ThreadDispatchDisabledCount>77908688</ThreadDispatchDisabledCount>
5459    <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
5460    <MaxInterruptTime unit="ns">688</MaxInterruptTime>
5461    <MeanInterruptTime unit="ns">127</MeanInterruptTime>
5462    <TotalInterruptTime unit="ns">282651157</TotalInterruptTime>
5463    <InterruptCount>2215855</InterruptCount>
5464    </PerCPUProfilingReport>
5465    <PerCPUProfilingReport processorIndex="1">
5466    <MaxThreadDispatchDisabledTime unit="ns">9053</MaxThreadDispatchDisabledTime>
5467    <MeanThreadDispatchDisabledTime unit="ns">41</MeanThreadDispatchDisabledTime>
5468    <TotalThreadDispatchDisabledTime unit="ns">3053830335</TotalThreadDispatchDisabledTime>
5469    <ThreadDispatchDisabledCount>73334202</ThreadDispatchDisabledCount>
5470    <MaxInterruptDelay unit="ns">0</MaxInterruptDelay>
5471    <MaxInterruptTime unit="ns">57</MaxInterruptTime>
5472    <MeanInterruptTime unit="ns">35</MeanInterruptTime>
5473    <TotalInterruptTime unit="ns">76980203</TotalInterruptTime>
5474    <InterruptCount>2141179</InterruptCount>
5475    </PerCPUProfilingReport>
5476    <SMPLockProfilingReport name="SMP lock stats">
5477    <MaxAcquireTime unit="ns">608</MaxAcquireTime>
5478    <MaxSectionTime unit="ns">1387</MaxSectionTime>
5479    <MeanAcquireTime unit="ns">112</MeanAcquireTime>
5480    <MeanSectionTime unit="ns">338</MeanSectionTime>
5481    <TotalAcquireTime unit="ns">119031</TotalAcquireTime>
5482    <TotalSectionTime unit="ns">357222</TotalSectionTime>
5483    <UsageCount>1055</UsageCount>
5484    <ContentionCount initialQueueLength="0">1055</ContentionCount>
5485    <ContentionCount initialQueueLength="1">0</ContentionCount>
5486    <ContentionCount initialQueueLength="2">0</ContentionCount>
5487    <ContentionCount initialQueueLength="3">0</ContentionCount>
5488    </SMPLockProfilingReport>
5489    <SMPLockProfilingReport name="Giant">
5490    <MaxAcquireTime unit="ns">4186</MaxAcquireTime>
5491    <MaxSectionTime unit="ns">7575</MaxSectionTime>
5492    <MeanAcquireTime unit="ns">160</MeanAcquireTime>
5493    <MeanSectionTime unit="ns">183</MeanSectionTime>
5494    <TotalAcquireTime unit="ns">1772793111</TotalAcquireTime>
5495    <TotalSectionTime unit="ns">2029733879</TotalSectionTime>
5496    <UsageCount>11039140</UsageCount>
5497    <ContentionCount initialQueueLength="0">11037655</ContentionCount>
5498    <ContentionCount initialQueueLength="1">1485</ContentionCount>
5499    <ContentionCount initialQueueLength="2">0</ContentionCount>
5500    <ContentionCount initialQueueLength="3">0</ContentionCount>
5501    </SMPLockProfilingReport>
5502    </ProfilingReport>
5503
5504**CONFIGURATION:**
5505
5506.. index:: CONFIGURE_SHELL_NO_COMMAND_PROFREPORT
5507.. index:: CONFIGURE_SHELL_COMMAND_PROFREPORT
5508
5509When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PROFREPORT`` to have this
5510command included.
5511
5512This command can be excluded from the shell command set by
5513defining ``CONFIGURE_SHELL_NO_COMMAND_PROFREPORT`` when all
5514shell commands have been configured.
5515
5516**PROGRAMMING INFORMATION:**
5517
5518The configuration structure for the ``profreport`` has the
5519following prototype:
5520.. code:: c
5521
5522    extern rtems_shell_cmd_t rtems_shell_PROFREPORT_Command;
5523
5524wkspace - display information on executive workspace
5525----------------------------------------------------
5526.. index:: wkspace
5527
5528**SYNOPSYS:**
5529
5530.. code:: c
5531
5532    wkspace
5533
5534**DESCRIPTION:**
5535
5536This command prints information on the current state of
5537the RTEMS Executive Workspace reported.  This includes the
5538following information:
5539
5540- Number of free blocks
5541
5542- Largest free block
5543
5544- Total bytes free
5545
5546- Number of used blocks
5547
5548- Largest used block
5549
5550- Total bytes used
5551
5552**EXIT STATUS:**
5553
5554This command always succeeds and returns 0.
5555
5556**NOTES:**
5557
5558NONE
5559
5560**EXAMPLES:**
5561
5562The following is an example of how to use ``wkspace``:
5563.. code:: c
5564
5565    SHLL \[/] $ wkspace
5566    Number of free blocks: 1
5567    Largest free block:    132336
5568    Total bytes free:      132336
5569    Number of used blocks: 36
5570    Largest used block:    16408
5571    Total bytes used:      55344
5572
5573**CONFIGURATION:**
5574
5575.. index:: CONFIGURE_SHELL_NO_COMMAND_WKSPACE
5576.. index:: CONFIGURE_SHELL_COMMAND_WKSPACE
5577
5578This command is included in the default shell command set.
5579When building a custom command set, define``CONFIGURE_SHELL_COMMAND_WKSPACE`` to have this
5580command included.
5581
5582This command can be excluded from the shell command set by
5583defining ``CONFIGURE_SHELL_NO_COMMAND_WKSPACE`` when all
5584shell commands have been configured.
5585
5586**PROGRAMMING INFORMATION:**
5587
5588.. index:: rtems_shell_rtems_main_wkspace
5589
5590The ``wkspace`` is implemented by a C language function
5591which has the following prototype:
5592.. code:: c
5593
5594    int rtems_shell_rtems_main_wkspace(
5595    int    argc,
5596    char \**argv
5597    );
5598
5599The configuration structure for the ``wkspace`` has the
5600following prototype:
5601.. code:: c
5602
5603    extern rtems_shell_cmd_t rtems_shell_WKSPACE_Command;
5604
5605config - show the system configuration.
5606---------------------------------------
5607.. index:: config
5608
5609**SYNOPSYS:**
5610
5611.. code:: c
5612
5613    config
5614
5615**DESCRIPTION:**
5616
5617This command display information about the RTEMS Configuration.
5618
5619**EXIT STATUS:**
5620
5621This command always succeeds and returns 0.
5622
5623**NOTES:**
5624
5625At this time, it does not report every configuration parameter.
5626This is an area in which user submissions or sponsorship of
5627a developer would be appreciated.
5628
5629**EXAMPLES:**
5630
5631The following is an example of how to use ``config``:
5632.. code:: c
5633
5634    INITIAL (startup) Configuration Info
5635    ------------------------------------------------------------------------------
5636    WORKSPACE      start: 0x23d22e0;  size: 0x2dd20
5637    TIME           usec/tick: 10000;  tick/timeslice: 50;  tick/sec: 100
5638    MAXIMUMS       tasks: 20;  timers: 0;  sems: 50;  que's: 20;  ext's: 1
5639    partitions: 0;  regions: 0;  ports: 0;  periods: 0
5640
5641**CONFIGURATION:**
5642
5643.. index:: CONFIGURE_SHELL_NO_COMMAND_CONFIG
5644.. index:: CONFIGURE_SHELL_COMMAND_CONFIG
5645
5646This command is included in the default shell command set.
5647When building a custom command set, define``CONFIGURE_SHELL_COMMAND_CONFIG`` to have this
5648command included.
5649
5650This command can be excluded from the shell command set by
5651defining ``CONFIGURE_SHELL_NO_COMMAND_CONFIG`` when all
5652shell commands have been configured.
5653
5654**PROGRAMMING INFORMATION:**
5655
5656.. index:: rtems_shell_rtems_main_config
5657
5658The ``config`` is implemented by a C language function
5659which has the following prototype:
5660.. code:: c
5661
5662    int rtems_shell_rtems_main_config(
5663    int    argc,
5664    char \**argv
5665    );
5666
5667The configuration structure for the ``config`` has the
5668following prototype:
5669.. code:: c
5670
5671    extern rtems_shell_cmd_t rtems_shell_CONFIG_Command;
5672
5673itask - list init tasks for the system
5674--------------------------------------
5675.. index:: itask
5676
5677**SYNOPSYS:**
5678
5679.. code:: c
5680
5681    itask
5682
5683**DESCRIPTION:**
5684
5685This command prints a report on the set of initialization
5686tasks and threads in the system.
5687
5688**EXIT STATUS:**
5689
5690This command always succeeds and returns 0.
5691
5692**NOTES:**
5693
5694At this time, it includes only Classic API Initialization Tasks.
5695This is an area in which user submissions or sponsorship of
5696a developer would be appreciated.
5697
5698**EXAMPLES:**
5699
5700The following is an example of how to use ``itask``:
5701.. code:: c
5702
5703    SHLL \[/] $ itask
5704    #    NAME   ENTRY        ARGUMENT    PRIO   MODES  ATTRIBUTES   STACK SIZE
5705    ------------------------------------------------------------------------------
5706    0   UI1    \[0x2002258] 0 \[0x0]        1    nP      DEFAULT     4096 \[0x1000]
5707
5708**CONFIGURATION:**
5709
5710.. index:: CONFIGURE_SHELL_NO_COMMAND_ITASK
5711.. index:: CONFIGURE_SHELL_COMMAND_ITASK
5712
5713This command is included in the default shell command set.
5714When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ITASK`` to have this
5715command included.
5716
5717This command can be excluded from the shell command set by
5718defining ``CONFIGURE_SHELL_NO_COMMAND_ITASK`` when all
5719shell commands have been configured.
5720
5721**PROGRAMMING INFORMATION:**
5722
5723.. index:: rtems_shell_rtems_main_itask
5724
5725The ``itask`` is implemented by a C language function
5726which has the following prototype:
5727.. code:: c
5728
5729    int rtems_shell_rtems_main_itask(
5730    int    argc,
5731    char \**argv
5732    );
5733
5734The configuration structure for the ``itask`` has the
5735following prototype:
5736.. code:: c
5737
5738    extern rtems_shell_cmd_t rtems_shell_ITASK_Command;
5739
5740extension - display information about extensions
5741------------------------------------------------
5742.. index:: extension
5743
5744**SYNOPSYS:**
5745
5746.. code:: c
5747
5748    extension \[id \[id ...] ]
5749
5750**DESCRIPTION:**
5751
5752When invoked with no arguments, this command prints information on
5753the set of User Extensions currently active in the system.
5754
5755If invoked with a set of ids as arguments, then just
5756those objects are included in the information printed.
5757
5758**EXIT STATUS:**
5759
5760This command returns 0 on success and non-zero if an error is encountered.
5761
5762**NOTES:**
5763
5764NONE
5765
5766**EXAMPLES:**
5767
5768The following is an example of using the ``extension`` command
5769on a system with no user extensions.
5770.. code:: c
5771
5772    SHLL \[/] $ extension
5773    ID       NAME
5774    ------------------------------------------------------------------------------
5775
5776**CONFIGURATION:**
5777
5778.. index:: CONFIGURE_SHELL_NO_COMMAND_EXTENSION
5779.. index:: CONFIGURE_SHELL_COMMAND_EXTENSION
5780
5781This command is included in the default shell command set.
5782When building a custom command set, define``CONFIGURE_SHELL_COMMAND_EXTENSION`` to have this
5783command included.
5784
5785This command can be excluded from the shell command set by
5786defining ``CONFIGURE_SHELL_NO_COMMAND_EXTENSION`` when all
5787shell commands have been configured.
5788
5789**PROGRAMMING INFORMATION:**
5790
5791.. index:: rtems_shell_rtems_main_extension
5792
5793The ``extension`` is implemented by a C language function
5794which has the following prototype:
5795.. code:: c
5796
5797    int rtems_shell_rtems_main_extension(
5798    int    argc,
5799    char \**argv
5800    );
5801
5802The configuration structure for the ``extension`` has the
5803following prototype:
5804.. code:: c
5805
5806    extern rtems_shell_cmd_t rtems_shell_EXTENSION_Command;
5807
5808task - display information about tasks
5809--------------------------------------
5810.. index:: task
5811
5812**SYNOPSYS:**
5813
5814.. code:: c
5815
5816    task \[id \[id ...] ]
5817
5818**DESCRIPTION:**
5819
5820When invoked with no arguments, this command prints information on
5821the set of Classic API Tasks currently active in the system.
5822
5823If invoked with a set of ids as arguments, then just
5824those objects are included in the information printed.
5825
5826**EXIT STATUS:**
5827
5828This command returns 0 on success and non-zero if an error is encountered.
5829
5830**NOTES:**
5831
5832NONE
5833
5834**EXAMPLES:**
5835
5836The following is an example of how to use the ``task`` on an
5837application with just two Classic API tasks:
5838.. code:: c
5839
5840    SHLL \[/] $ task
5841    ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
5842    ------------------------------------------------------------------------------
5843    0a010001   UI1      1   SUSP   P:T:nA  NONE
5844    0a010002   SHLL   100   READY  P:T:nA  NONE
5845
5846**CONFIGURATION:**
5847
5848.. index:: CONFIGURE_SHELL_NO_COMMAND_TASK
5849.. index:: CONFIGURE_SHELL_COMMAND_TASK
5850
5851This command is included in the default shell command set.
5852When building a custom command set, define``CONFIGURE_SHELL_COMMAND_TASK`` to have this
5853command included.
5854
5855This command can be excluded from the shell command set by
5856defining ``CONFIGURE_SHELL_NO_COMMAND_TASK`` when all
5857shell commands have been configured.
5858
5859**PROGRAMMING INFORMATION:**
5860
5861.. index:: rtems_shell_rtems_main_task
5862
5863The ``task`` is implemented by a C language function
5864which has the following prototype:
5865.. code:: c
5866
5867    int rtems_shell_rtems_main_task(
5868    int    argc,
5869    char \**argv
5870    );
5871
5872The configuration structure for the ``task`` has the
5873following prototype:
5874.. code:: c
5875
5876    extern rtems_shell_cmd_t rtems_shell_TASK_Command;
5877
5878queue - display information about message queues
5879------------------------------------------------
5880.. index:: queue
5881
5882**SYNOPSYS:**
5883
5884.. code:: c
5885
5886    queue \[id \[id ... ] ]
5887
5888**DESCRIPTION:**
5889
5890When invoked with no arguments, this command prints information on
5891the set of Classic API Message Queues currently active in the system.
5892
5893If invoked with a set of ids as arguments, then just
5894those objects are included in the information printed.
5895
5896**EXIT STATUS:**
5897
5898This command returns 0 on success and non-zero if an error is encountered.
5899
5900**NOTES:**
5901
5902NONE
5903
5904**EXAMPLES:**
5905
5906The following is an example of using the ``queue`` command
5907on a system with no Classic API Message Queues.
5908.. code:: c
5909
5910    SHLL \[/] $ queue
5911    ID       NAME   ATTRIBUTES   PEND   MAXPEND  MAXSIZE
5912    ------------------------------------------------------------------------------
5913
5914**CONFIGURATION:**
5915
5916.. index:: CONFIGURE_SHELL_NO_COMMAND_QUEUE
5917.. index:: CONFIGURE_SHELL_COMMAND_QUEUE
5918
5919This command is included in the default shell command set.
5920When building a custom command set, define``CONFIGURE_SHELL_COMMAND_QUEUE`` to have this
5921command included.
5922
5923This command can be excluded from the shell command set by
5924defining ``CONFIGURE_SHELL_NO_COMMAND_QUEUE`` when all
5925shell commands have been configured.
5926
5927**PROGRAMMING INFORMATION:**
5928
5929.. index:: rtems_shell_rtems_main_queue
5930
5931The ``queue`` is implemented by a C language function
5932which has the following prototype:
5933.. code:: c
5934
5935    int rtems_shell_rtems_main_queue(
5936    int    argc,
5937    char \**argv
5938    );
5939
5940The configuration structure for the ``queue`` has the
5941following prototype:
5942.. code:: c
5943
5944    extern rtems_shell_cmd_t rtems_shell_QUEUE_Command;
5945
5946sema - display information about semaphores
5947-------------------------------------------
5948.. index:: sema
5949
5950**SYNOPSYS:**
5951
5952.. code:: c
5953
5954    sema \[id \[id ... ] ]
5955
5956**DESCRIPTION:**
5957
5958When invoked with no arguments, this command prints information on
5959the set of Classic API Semaphores currently active in the system.
5960
5961If invoked with a set of objects ids as arguments, then just
5962those objects are included in the information printed.
5963
5964**EXIT STATUS:**
5965
5966This command returns 0 on success and non-zero if an error is encountered.
5967
5968**NOTES:**
5969
5970NONE
5971
5972**EXAMPLES:**
5973
5974The following is an example of how to use ``sema``:
5975.. code:: c
5976
5977    SHLL \[/] $ sema
5978    ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID
5979    ------------------------------------------------------------------------------
5980    1a010001   LBIO   PR:BI:IN      0        1     00000000
5981    1a010002   TRmi   PR:BI:IN      0        1     00000000
5982    1a010003   LBI00  PR:BI:IN      0        1     00000000
5983    1a010004   TRia   PR:BI:IN      0        1     00000000
5984    1a010005   TRoa   PR:BI:IN      0        1     00000000
5985    1a010006   TRxa   <assoc.c: BAD NAME>   0    0 09010001
5986    1a010007   LBI01  PR:BI:IN      0        1     00000000
5987    1a010008   LBI02  PR:BI:IN      0        1     00000000
5988
5989**CONFIGURATION:**
5990
5991.. index:: CONFIGURE_SHELL_NO_COMMAND_SEMA
5992.. index:: CONFIGURE_SHELL_COMMAND_SEMA
5993
5994This command is included in the default shell command set.
5995When building a custom command set, define``CONFIGURE_SHELL_COMMAND_SEMA`` to have this
5996command included.
5997
5998This command can be excluded from the shell command set by
5999defining ``CONFIGURE_SHELL_NO_COMMAND_SEMA`` when all
6000shell commands have been configured.
6001
6002**PROGRAMMING INFORMATION:**
6003
6004.. index:: rtems_shell_rtems_main_sema
6005
6006The ``sema`` is implemented by a C language function
6007which has the following prototype:
6008.. code:: c
6009
6010    int rtems_shell_rtems_main_sema(
6011    int    argc,
6012    char \**argv
6013    );
6014
6015The configuration structure for the ``sema`` has the
6016following prototype:
6017.. code:: c
6018
6019    extern rtems_shell_cmd_t rtems_shell_SEMA_Command;
6020
6021region - display information about regions
6022------------------------------------------
6023.. index:: region
6024
6025**SYNOPSYS:**
6026
6027.. code:: c
6028
6029    region \[id \[id ... ] ]
6030
6031**DESCRIPTION:**
6032
6033When invoked with no arguments, this command prints information on
6034the set of Classic API Regions currently active in the system.
6035
6036If invoked with a set of object ids as arguments, then just
6037those object are included in the information printed.
6038
6039**EXIT STATUS:**
6040
6041This command returns 0 on success and non-zero if an error is encountered.
6042
6043**NOTES:**
6044
6045NONE
6046
6047**EXAMPLES:**
6048
6049The following is an example of using the ``region`` command
6050on a system with no user extensions.
6051.. code:: c
6052
6053    SHLL \[/] $ region
6054    ID       NAME   ATTR        STARTADDR LENGTH    PAGE_SIZE USED_BLOCKS
6055    ------------------------------------------------------------------------------
6056
6057**CONFIGURATION:**
6058
6059.. index:: CONFIGURE_SHELL_NO_COMMAND_REGION
6060.. index:: CONFIGURE_SHELL_COMMAND_REGION
6061
6062This command is included in the default shell command set.
6063When building a custom command set, define``CONFIGURE_SHELL_COMMAND_REGION`` to have this
6064command included.
6065
6066This command can be excluded from the shell command set by
6067defining ``CONFIGURE_SHELL_NO_COMMAND_REGION`` when all
6068shell commands have been configured.
6069
6070**PROGRAMMING INFORMATION:**
6071
6072.. index:: rtems_shell_rtems_main_region
6073
6074The ``region`` is implemented by a C language function
6075which has the following prototype:
6076.. code:: c
6077
6078    int rtems_shell_rtems_main_region(
6079    int    argc,
6080    char \**argv
6081    );
6082
6083The configuration structure for the ``region`` has the
6084following prototype:
6085.. code:: c
6086
6087    extern rtems_shell_cmd_t rtems_shell_REGION_Command;
6088
6089part - display information about partitions
6090-------------------------------------------
6091.. index:: part
6092
6093**SYNOPSYS:**
6094
6095.. code:: c
6096
6097    part \[id \[id ... ] ]
6098
6099**DESCRIPTION:**
6100
6101When invoked with no arguments, this command prints information on
6102the set of Classic API Partitions currently active in the system.
6103
6104If invoked with a set of object ids as arguments, then just
6105those objects are included in the information printed.
6106
6107**EXIT STATUS:**
6108
6109This command returns 0 on success and non-zero if an error is encountered.
6110
6111**NOTES:**
6112
6113NONE
6114
6115**EXAMPLES:**
6116
6117The following is an example of using the ``part`` command
6118on a system with no user extensions.
6119.. code:: c
6120
6121    SHLL \[/] $ part
6122    ID       NAME   ATTR        STARTADDR LENGTH    BUF_SIZE  USED_BLOCKS
6123    ------------------------------------------------------------------------------
6124
6125**CONFIGURATION:**
6126
6127.. index:: CONFIGURE_SHELL_NO_COMMAND_PART
6128.. index:: CONFIGURE_SHELL_COMMAND_PART
6129
6130This command is included in the default shell command set.
6131When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PART`` to have this
6132command included.
6133
6134This command can be excluded from the shell command set by
6135defining ``CONFIGURE_SHELL_NO_COMMAND_PART`` when all
6136shell commands have been configured.
6137
6138**PROGRAMMING INFORMATION:**
6139
6140.. index:: rtems_shell_rtems_main_part
6141
6142The ``part`` is implemented by a C language function
6143which has the following prototype:
6144.. code:: c
6145
6146    int rtems_shell_rtems_main_part(
6147    int    argc,
6148    char \**argv
6149    );
6150
6151The configuration structure for the ``part`` has the
6152following prototype:
6153.. code:: c
6154
6155    extern rtems_shell_cmd_t rtems_shell_PART_Command;
6156
6157object - display information about rtems objects
6158------------------------------------------------
6159.. index:: object
6160
6161**SYNOPSYS:**
6162
6163.. code:: c
6164
6165    object \[id \[id ...] ]
6166
6167**DESCRIPTION:**
6168
6169When invoked with a set of object ids as arguments, then
6170a report on those objects is printed.
6171
6172**EXIT STATUS:**
6173
6174This command returns 0 on success and non-zero if an error is encountered.
6175
6176**NOTES:**
6177
6178NONE
6179
6180**EXAMPLES:**
6181
6182The following is an example of how to use ``object``:
6183.. code:: c
6184
6185    SHLL \[/] $ object 0a010001 1a010002
6186    ID       NAME   PRIO   STAT   MODES  EVENTS   WAITID  WAITARG  NOTES
6187    ------------------------------------------------------------------------------
6188    0a010001   UI1      1   SUSP   P:T:nA  NONE
6189    ID       NAME   ATTR        PRICEIL CURR_CNT HOLDID
6190    ------------------------------------------------------------------------------
6191    1a010002   TRmi   PR:BI:IN      0        1     00000000
6192
6193**CONFIGURATION:**
6194
6195.. index:: CONFIGURE_SHELL_NO_COMMAND_OBJECT
6196.. index:: CONFIGURE_SHELL_COMMAND_OBJECT
6197
6198This command is included in the default shell command set.
6199When building a custom command set, define``CONFIGURE_SHELL_COMMAND_OBJECT`` to have this
6200command included.
6201
6202This command can be excluded from the shell command set by
6203defining ``CONFIGURE_SHELL_NO_COMMAND_OBJECT`` when all
6204shell commands have been configured.
6205
6206**PROGRAMMING INFORMATION:**
6207
6208.. index:: rtems_shell_rtems_main_object
6209
6210The ``object`` is implemented by a C language function
6211which has the following prototype:
6212.. code:: c
6213
6214    int rtems_shell_rtems_main_object(
6215    int    argc,
6216    char \**argv
6217    );
6218
6219The configuration structure for the ``object`` has the
6220following prototype:
6221.. code:: c
6222
6223    extern rtems_shell_cmd_t rtems_shell_OBJECT_Command;
6224
6225driver - display the rtems device driver table
6226----------------------------------------------
6227.. index:: driver
6228
6229**SYNOPSYS:**
6230
6231.. code:: c
6232
6233    driver [ major [ major ... ] ]
6234
6235**DESCRIPTION:**
6236
6237When invoked with no arguments, this command prints information on
6238the set of Device Drivers currently active in the system.
6239
6240If invoked with a set of major numbers as arguments, then just
6241those Device Drivers are included in the information printed.
6242
6243**EXIT STATUS:**
6244
6245This command returns 0 on success and non-zero if an error is encountered.
6246
6247**NOTES:**
6248
6249NONE
6250
6251**EXAMPLES:**
6252
6253The following is an example of how to use ``driver``:
6254.. code:: c
6255
6256    SHLL \[/] $ driver
6257    Major      Entry points
6258    ------------------------------------------------------------------------------
6259    0          init: \[0x200256c];  control: \[0x20024c8]
6260    open: \[0x2002518];  close: \[0x2002504]
6261    read: \[0x20024f0];  write: \[0x20024dc]
6262    1          init: \[0x20023fc];  control: \[0x2002448]
6263    open: \[0x0];  close: \[0x0]
6264    read: \[0x0];  write: \[0x0]
6265    SHLL \[/] $
6266
6267**CONFIGURATION:**
6268
6269.. index:: CONFIGURE_SHELL_NO_COMMAND_DRIVER
6270.. index:: CONFIGURE_SHELL_COMMAND_DRIVER
6271
6272This command is included in the default shell command set.
6273When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DRIVER`` to have this
6274command included.
6275
6276This command can be excluded from the shell command set by
6277defining ``CONFIGURE_SHELL_NO_COMMAND_DRIVER`` when all
6278shell commands have been configured.
6279
6280**PROGRAMMING INFORMATION:**
6281
6282.. index:: rtems_shell_rtems_main_driver
6283
6284The ``driver`` is implemented by a C language function
6285which has the following prototype:
6286.. code:: c
6287
6288    int rtems_shell_rtems_main_driver(
6289    int    argc,
6290    char \**argv
6291    );
6292
6293The configuration structure for the ``driver`` has the
6294following prototype:
6295.. code:: c
6296
6297    extern rtems_shell_cmd_t rtems_shell_DRIVER_Command;
6298
6299dname - displays information about named drivers
6300------------------------------------------------
6301.. index:: dname
6302
6303**SYNOPSYS:**
6304
6305.. code:: c
6306
6307    dname
6308
6309**DESCRIPTION:**
6310
6311This command XXX
6312
6313WARNING! XXX This command does not appear to work as of 27 February 2008.
6314
6315**EXIT STATUS:**
6316
6317This command returns 0 on success and non-zero if an error is encountered.
6318
6319**NOTES:**
6320
6321NONE
6322
6323**EXAMPLES:**
6324
6325The following is an example of how to use ``dname``:
6326.. code:: c
6327
6328    EXAMPLE_TBD
6329
6330**CONFIGURATION:**
6331
6332.. index:: CONFIGURE_SHELL_NO_COMMAND_DNAME
6333.. index:: CONFIGURE_SHELL_COMMAND_DNAME
6334
6335This command is included in the default shell command set.
6336When building a custom command set, define``CONFIGURE_SHELL_COMMAND_DNAME`` to have this
6337command included.
6338
6339This command can be excluded from the shell command set by
6340defining ``CONFIGURE_SHELL_NO_COMMAND_DNAME`` when all
6341shell commands have been configured.
6342
6343**PROGRAMMING INFORMATION:**
6344
6345.. index:: rtems_shell_rtems_main_dname
6346
6347The ``dname`` is implemented by a C language function
6348which has the following prototype:
6349.. code:: c
6350
6351    int rtems_shell_rtems_main_dname(
6352    int    argc,
6353    char \**argv
6354    );
6355
6356The configuration structure for the ``dname`` has the
6357following prototype:
6358.. code:: c
6359
6360    extern rtems_shell_cmd_t rtems_shell_DNAME_Command;
6361
6362pthread - display information about POSIX threads
6363-------------------------------------------------
6364.. index:: pthread
6365
6366**SYNOPSYS:**
6367
6368.. code:: c
6369
6370    pthread \[id \[id ...] ]
6371
6372**DESCRIPTION:**
6373
6374When invoked with no arguments, this command prints information on
6375the set of POSIX API threads currently active in the system.
6376
6377If invoked with a set of ids as arguments, then just
6378those objects are included in the information printed.
6379
6380**EXIT STATUS:**
6381
6382This command returns 0 on success and non-zero if an error is encountered.
6383
6384**NOTES:**
6385
6386This command is only available when the POSIX API is configured.
6387
6388**EXAMPLES:**
6389
6390The following is an example of how to use the ``task`` on an
6391application with four POSIX threads:
6392.. code:: c
6393
6394    SHLL \[/] $ pthread
6395    ID       NAME           PRI  STATE MODES   EVENTS    WAITID  WAITARG  NOTES
6396    ------------------------------------------------------------------------------
6397    0b010002   Main           133 READY  P:T:nA    NONE   43010001 0x7b1148
6398    0b010003   ISR            133 Wcvar  P:T:nA    NONE   43010003 0x7b1148
6399    0b01000c                  133 READY  P:T:nA    NONE   33010002 0x7b1148
6400    0b01000d                  133 Wmutex P:T:nA    NONE   33010002 0x7b1148
6401
6402**CONFIGURATION:**
6403
6404This command is part of the monitor commands which are always
6405available in the shell.
6406
6407**PROGRAMMING INFORMATION:**
6408
6409This command is not directly available for invocation.
6410
6411.. COMMENT: COPYRIGHT (c) 1988-2008.
6412
6413.. COMMENT: On-Line Applications Research Corporation (OAR).
6414
6415.. COMMENT: All rights reserved.
6416
6417Network Commands
6418################
6419
6420Introduction
6421============
6422
6423The RTEMS shell has the following network commands:
6424
6425- ``netstats`` - obtain network statistics
6426
6427- ``ifconfig`` - configure a network interface
6428
6429- ``route`` - show or manipulate the IP routing table
6430
6431- ``ping`` - ping a host or IP address
6432
6433Commands
6434========
6435
6436This section details the Network Commands available.  A
6437subsection is dedicated to each of the commands and
6438describes the behavior and configuration of that
6439command as well as providing an example usage.
6440
6441netstats - obtain network statistics
6442------------------------------------
6443.. index:: netstats
6444
6445**SYNOPSYS:**
6446
6447.. code:: c
6448
6449    netstats \[-Aimfpcut]
6450
6451**DESCRIPTION:**
6452
6453This command is used to display various types of network statistics.  The
6454information displayed can be specified using command line arguments in
6455various combinations.  The arguments are interpreted as follows:
6456
6457*-A*
6458    print All statistics
6459
6460*-i*
6461    print Inet Routes
6462
6463*-m*
6464    print MBUF Statistics
6465
6466*-f*
6467    print IF Statistics
6468
6469*-p*
6470    print IP Statistics
6471
6472*-c*
6473    print ICMP Statistics
6474
6475*-u*
6476    print UDP Statistics
6477
6478*-t*
6479    print TCP Statistics
6480
6481**EXIT STATUS:**
6482
6483This command returns 0 on success and non-zero if an error is encountered.
6484
6485**NOTES:**
6486
6487NONE
6488
6489**EXAMPLES:**
6490
6491The following is an example of how to use ``netstats``:
6492
6493The following is an example of using the ``netstats``
6494command to print the IP routing table:
6495.. code:: c
6496
6497    [/] $ netstats -i
6498    Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
6499    default         192.168.1.14       UGS         0        0      0 eth1
6500    192.168.1.0     255.255.255.0      U           0        0      1 eth1
6501    192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1219 eth1
6502    192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0      840   1202 eth1
6503    192.168.1.151   00:1C:23:B2:0F:BB  UHL         1       23   1219 eth1
6504
6505The following is an example of using the ``netstats``
6506command to print the MBUF statistics:
6507.. code:: c
6508
6509    [/] $ netstats -m
6510    \************ MBUF STATISTICS \************
6511    mbufs:2048    clusters: 128    free:  63
6512    drops:   0       waits:   0  drains:   0
6513    free:1967          data:79          header:2           socket:0
6514    pcb:0           rtable:0           htable:0           atable:0
6515    soname:0           soopts:0           ftable:0           rights:0
6516    ifaddr:0          control:0          oobdata:0
6517
6518The following is an example of using the ``netstats``
6519command to print the print the interface statistics:
6520.. code:: c
6521
6522    [/] $ netstats -f
6523    \************ INTERFACE STATISTICS \************
6524    \***** eth1 \*****
6525    Ethernet Address: 00:04:9F:00:5B:21
6526    Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
6527    Flags: Up Broadcast Running Active Multicast
6528    Send queue limit:50   length:1    Dropped:0
6529    Rx Interrupts:889            Not First:0               Not Last:0
6530    Giant:0              Non-octet:0
6531    Bad CRC:0                Overrun:0              Collision:0
6532    Tx Interrupts:867             Deferred:0         Late Collision:0
6533    Retransmit Limit:0               Underrun:0             Misaligned:0
6534
6535The following is an example of using the ``netstats``
6536command to print the print IP statistics:
6537.. code:: c
6538
6539    [/] $ netstats -p
6540    \************ IP Statistics \************
6541    total packets received         894
6542    packets rcvd for unreachable dest          13
6543    datagrams delivered to upper level         881
6544    total ip packets generated here         871
6545
6546The following is an example of using the ``netstats``
6547command to print the ICMP statistics:
6548.. code:: c
6549
6550    [/] $ netstats -c
6551    \************ ICMP Statistics \************
6552    Type 0 sent         843
6553    number of responses         843
6554    Type 8 received         843
6555
6556The following is an example of using the ``netstats``
6557command to print the UDP statistics:
6558.. code:: c
6559
6560    [/] $ netstats -u
6561    \************ UDP Statistics \************
6562
6563The following is an example of using the ``netstats``
6564command to print the TCP statistics:
6565.. code:: c
6566
6567    [/] $ netstats -t
6568    \************ TCP Statistics \************
6569    connections accepted           1
6570    connections established           1
6571    segs where we tried to get rtt          34
6572    times we succeeded          35
6573    delayed acks sent           2
6574    total packets sent          37
6575    data packets sent          35
6576    data bytes sent        2618
6577    ack-only packets sent           2
6578    total packets received          47
6579    packets received in sequence          12
6580    bytes received in sequence         307
6581    rcvd ack packets          35
6582    bytes acked by rcvd acks        2590
6583    times hdr predict ok for acks          27
6584    times hdr predict ok for data pkts          10
6585
6586**CONFIGURATION:**
6587
6588.. index:: CONFIGURE_SHELL_NO_COMMAND_NETSTATS
6589.. index:: CONFIGURE_SHELL_COMMAND_NETSTATS
6590
6591This command is included in the default shell command set.
6592When building a custom command set, define``CONFIGURE_SHELL_COMMAND_NETSTATS`` to have this
6593command included.
6594
6595This command can be excluded from the shell command set by
6596defining ``CONFIGURE_SHELL_NO_COMMAND_NETSTATS`` when all
6597shell commands have been configured.
6598
6599**PROGRAMMING INFORMATION:**
6600
6601.. index:: rtems_shell_rtems_main_netstats
6602
6603The ``netstats`` is implemented by a C language function
6604which has the following prototype:
6605.. code:: c
6606
6607    int rtems_shell_rtems_main_netstats(
6608    int    argc,
6609    char \**argv
6610    );
6611
6612The configuration structure for the ``netstats`` has the
6613following prototype:
6614.. code:: c
6615
6616    extern rtems_shell_cmd_t rtems_shell_NETSTATS_Command;
6617
6618ifconfig - configure a network interface
6619----------------------------------------
6620.. index:: ifconfig
6621
6622**SYNOPSYS:**
6623
6624.. code:: c
6625
6626    ifconfig
6627    ifconfig interface
6628    ifconfig interface \[up|down]
6629    ifconfig interface \[netmask|pointtopoint|broadcast] IP
6630
6631**DESCRIPTION:**
6632
6633This command may be used to display information about the
6634network interfaces in the system or configure them.
6635
6636**EXIT STATUS:**
6637
6638This command returns 0 on success and non-zero if an error is encountered.
6639
6640**NOTES:**
6641
6642Just like its counterpart on GNU/Linux and BSD systems, this command
6643is complicated.  More example usages would be a welcome submission.
6644
6645**EXAMPLES:**
6646
6647The following is an example of how to use ``ifconfig``:
6648.. code:: c
6649
6650    ************ INTERFACE STATISTICS \************
6651    \***** eth1 \*****
6652    Ethernet Address: 00:04:9F:00:5B:21
6653    Address:192.168.1.244   Broadcast Address:192.168.1.255   Net mask:255.255.255.0
6654    Flags: Up Broadcast Running Active Multicast
6655    Send queue limit:50   length:1    Dropped:0
6656    Rx Interrupts:5391           Not First:0               Not Last:0
6657    Giant:0              Non-octet:0
6658    Bad CRC:0                Overrun:0              Collision:0
6659    Tx Interrupts:5256            Deferred:0         Late Collision:0
6660    Retransmit Limit:0               Underrun:0             Misaligned:0
6661
6662**CONFIGURATION:**
6663
6664.. index:: CONFIGURE_SHELL_NO_COMMAND_IFCONFIG
6665.. index:: CONFIGURE_SHELL_COMMAND_IFCONFIG
6666
6667This command is included in the default shell command set.
6668When building a custom command set, define``CONFIGURE_SHELL_COMMAND_IFCONFIG`` to have this
6669command included.
6670
6671This command can be excluded from the shell command set by
6672defining ``CONFIGURE_SHELL_NO_COMMAND_IFCONFIG`` when all
6673shell commands have been configured.
6674
6675**PROGRAMMING INFORMATION:**
6676
6677.. index:: rtems_shell_rtems_main_ifconfig
6678
6679The ``ifconfig`` is implemented by a C language function
6680which has the following prototype:
6681.. code:: c
6682
6683    int rtems_shell_rtems_main_ifconfig(
6684    int    argc,
6685    char \**argv
6686    );
6687
6688The configuration structure for the ``ifconfig`` has the
6689following prototype:
6690.. code:: c
6691
6692    extern rtems_shell_cmd_t rtems_shell_IFCONFIG_Command;
6693
6694route - show or manipulate the ip routing table
6695-----------------------------------------------
6696.. index:: route
6697
6698**SYNOPSYS:**
6699
6700.. code:: c
6701
6702    route \[subcommand] \[args]
6703
6704**DESCRIPTION:**
6705
6706This command is used to display and manipulate the routing table.
6707When invoked with no arguments, the current routing information is
6708displayed.  When invoked with the subcommands ``add`` or ``del``,
6709then additional arguments must be provided to describe the route.
6710
6711Command templates include the following:
6712.. code:: c
6713
6714    route \[add|del] -net IP_ADDRESS gw GATEWAY_ADDRESS \[netmask MASK]
6715    route \[add|del] -host IP_ADDRESS gw GATEWAY_ADDRES \[netmask MASK]
6716
6717When not provided the netmask defaults to ``255.255.255.0``
6718
6719**EXIT STATUS:**
6720
6721This command returns 0 on success and non-zero if an error is encountered.
6722
6723**NOTES:**
6724
6725Just like its counterpart on GNU/Linux and BSD systems, this command
6726is complicated.  More example usages would be a welcome submission.
6727
6728**EXAMPLES:**
6729
6730The following is an example of how to use ``route`` to display,
6731add, and delete a new route:
6732.. code:: c
6733
6734    [/] $ route
6735    Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
6736    default         192.168.1.14       UGS         0        0      0 eth1
6737    192.168.1.0     255.255.255.0      U           0        0      1 eth1
6738    192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1444 eth1
6739    192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    10844   1202 eth1
6740    192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       37   1399 eth1
6741    \[/] $  route add -net 192.168.3.0 gw 192.168.1.14
6742    \[/] $ route
6743    Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
6744    default         192.168.1.14       UGS         0        0      0 eth1
6745    192.168.1.0     255.255.255.0      U           0        0      1 eth1
6746    192.168.1.14    00:A0:C8:1C:EE:28  UHL         2        0   1498 eth1
6747    192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    14937   1202 eth1
6748    192.168.1.151   00:1C:23:B2:0F:BB  UHL         2       96   1399 eth1
6749    192.168.3.0     192.168.1.14       UGS         0        0      0 eth1
6750    \[/] $ route del -net 192.168.3.0 gw 192.168.1.14
6751    \[/] $ route
6752    Destination     Gateway/Mask/Hw    Flags     Refs     Use Expire Interface
6753    default         192.168.1.14       UGS         0        0      0 eth1
6754    192.168.1.0     255.255.255.0      U           0        0      1 eth1
6755    192.168.1.14    00:A0:C8:1C:EE:28  UHL         1        0   1498 eth1
6756    192.168.1.51    00:1D:7E:0C:D0:7C  UHL         0    15945   1202 eth1
6757    192.168.1.151   00:1C:23:B2:0F:BB  UHL         2      117   1399 eth1
6758
6759**CONFIGURATION:**
6760
6761.. index:: CONFIGURE_SHELL_NO_COMMAND_ROUTE
6762.. index:: CONFIGURE_SHELL_COMMAND_ROUTE
6763
6764This command is included in the default shell command set.
6765When building a custom command set, define``CONFIGURE_SHELL_COMMAND_ROUTE`` to have this
6766command included.
6767
6768This command can be excluded from the shell command set by
6769defining ``CONFIGURE_SHELL_NO_COMMAND_ROUTE`` when all
6770shell commands have been configured.
6771
6772**PROGRAMMING INFORMATION:**
6773
6774.. index:: rtems_shell_rtems_main_route
6775
6776The ``route`` is implemented by a C language function
6777which has the following prototype:
6778.. code:: c
6779
6780    int rtems_shell_rtems_main_route(
6781    int    argc,
6782    char \**argv
6783    );
6784
6785The configuration structure for the ``route`` has the
6786following prototype:
6787.. code:: c
6788
6789    extern rtems_shell_cmd_t rtems_shell_ROUTE_Command;
6790
6791ping - ping a host or IP address
6792--------------------------------
6793.. index:: ping
6794
6795**SYNOPSYS:**
6796
6797.. code:: c
6798
6799    ping \[-AaDdfnoQqRrv] \[-c count] \[-G sweepmaxsize] \[-g sweepminsize]
6800    \[-h sweepincrsize] \[-i wait] \[-l preload] \[-M mask | time] \[-m ttl]
6801    \[-p pattern] \[-S src_addr] \[-s packetsize] \[-t timeout]
6802    \[-W waittime] \[-z tos] host
6803    ping \[-AaDdfLnoQqRrv] \[-c count] \[-I iface] \[-i wait] \[-l preload]
6804    \[-M mask | time] \[-m ttl] \[-p pattern] \[-S src_addr]
6805    \[-s packetsize] \[-T ttl] \[-t timeout] \[-W waittime]
6806    \[-z tos] mcast-group
6807
6808**DESCRIPTION:**
6809
6810The ping utility uses the ICMP protocol’s mandatory ECHO_REQUEST
6811datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
6812ECHO_REQUEST datagrams (“pings”) have an IP and ICMP header,
6813followed by a “struct timeval” and then an arbitrary number of
6814“pad” bytes used to fill out the packet.  The options are as
6815follows:
6816
6817*-A*
6818    Audible.  Output a bell (ASCII 0x07) character when no packet is
6819    received before the next packet is transmitted.  To cater for
6820    round-trip times that are longer than the interval between
6821    transmissions, further missing packets cause a bell only if the
6822    maximum number of unreceived packets has increased.
6823
6824*-a*
6825    Audible.  Include a bell (ASCII 0x07) character in the output when any
6826    packet is received.  This option is ignored if other format options
6827    are present.
6828
6829*-c count*
6830    Stop after sending (and receiving) count ECHO_RESPONSE packets.  If
6831    this option is not specified, ping will operate until interrupted.  If
6832    this option is specified in conjunction with ping sweeps, each sweep
6833    will consist of count packets.
6834
6835*-D*
6836    Set the Don’t Fragment bit.
6837
6838*-d*
6839    Set the SO_DEBUG option on the socket being used.
6840
6841*-f*
6842    Flood ping.  Outputs packets as fast as they come back or one
6843    hundred times per second, whichever is more.  For every ECHO_REQUEST
6844    sent a period “.” is printed, while for every ECHO_REPLY received a
6845    backspace is printed.  This provides a rapid display of how many
6846    packets are being dropped.  Only the super-user may use this option.
6847    This can be very hard on a network and should be used with caution.
6848
6849*-G sweepmaxsize*
6850    Specify the maximum size of ICMP payload when sending sweeping pings.
6851    This option is required for ping sweeps.
6852
6853*-g sweepminsize*
6854    Specify the size of ICMP payload to start with when sending sweeping
6855    pings.  The default value is 0.
6856
6857*-h sweepincrsize*
6858    Specify the number of bytes to increment the size of ICMP payload
6859    after each sweep when sending sweeping pings.  The default value is 1.
6860
6861*-I iface*
6862    Source multicast packets with the given interface address.  This flag
6863    only applies if the ping destination is a multicast address.
6864
6865*-i wait*
6866    Wait wait seconds between sending each packet.  The default is to wait
6867    for one second between each packet.  The wait time may be fractional,
6868    but only the super-user may specify values less than 1 second.  This
6869    option is incompatible with the -f option.
6870
6871*-L*
6872    Suppress loopback of multicast packets.  This flag only applies if the
6873    ping destination is a multicast address.
6874
6875*-l preload*
6876    If preload is specified, ping sends that many packets as fast as
6877    possible before falling into its normal mode of behavior.  Only the
6878    super-user may use this option.
6879
6880*-M mask | time*
6881    Use ICMP_MASKREQ or ICMP_TSTAMP instead of ICMP_ECHO.  For mask, print
6882    the netmask of the remote machine.  Set the net.inet.icmp.maskrepl MIB
6883    variable to enable ICMP_MASKREPLY.  For time, print the origination,
6884    reception and transmission timestamps.
6885
6886*-m ttl*
6887    Set the IP Time To Live for outgoing packets.  If not specified, the
6888    kernel uses the value of the net.inet.ip.ttl MIB variable.
6889
6890*-n*
6891    Numeric output only.  No attempt will be made to lookup symbolic names
6892    for host addresses.
6893
6894*-o*
6895    Exit successfully after receiving one reply packet.
6896
6897*-p pattern*
6898    You may specify up to 16 “pad” bytes to fill out the packet you
6899    send.  This is useful for diagnosing data-dependent problems in a
6900    network.  For example, “-p ff” will cause the sent packet to be
6901    filled with all ones.
6902
6903*-Q*
6904    Somewhat quiet output.  Don’t display ICMP error messages that are in
6905    response to our query messages.  Originally, the -v flag was required
6906    to display such errors, but -v displays all ICMP error messages.  On a
6907    busy machine, this output can be overbear- ing.  Without the -Q flag,
6908    ping prints out any ICMP error mes- sages caused by its own
6909    ECHO_REQUEST messages.
6910
6911*-q*
6912    Quiet output.  Nothing is displayed except the summary lines at
6913    startup time and when finished.
6914
6915*-R*
6916    Record route.  Includes the RECORD_ROUTE option in the ECHO_REQUEST
6917    packet and displays the route buffer on returned packets.  Note that
6918    the IP header is only large enough for nine such routes; the
6919    traceroute(8) command is usually better at determining the route
6920    packets take to a particular destination.  If more routes come back
6921    than should, such as due to an illegal spoofed packet, ping will print
6922    the route list and then truncate it at the correct spot.  Many hosts
6923    ignore or discard the RECORD_ROUTE option.
6924
6925*-r*
6926    Bypass the normal routing tables and send directly to a host on an
6927    attached network.  If the host is not on a directly-attached network,
6928    an error is returned.  This option can be used to ping a local host
6929    through an interface that has no route through it (e.g., after the
6930    interface was dropped).
6931
6932*-S src_addr*
6933    Use the following IP address as the source address in outgoing
6934    packets.  On hosts with more than one IP address, this option can be
6935    used to force the source address to be something other than the IP
6936    address of the interface the probe packet is sent on.  If the IP
6937    address is not one of this machine’s interface addresses, an error is
6938    returned and nothing is sent.
6939
6940*-s packetsize*
6941    Specify the number of data bytes to be sent.  The default is 56, which
6942    translates into 64 ICMP data bytes when combined with the 8 bytes of
6943    ICMP header data.  Only the super-user may specify val- ues more than
6944    default.  This option cannot be used with ping sweeps.
6945
6946*-T ttl*
6947    Set the IP Time To Live for multicasted packets.  This flag only
6948    applies if the ping destination is a multicast address.
6949
6950*-t timeout*
6951    Specify a timeout, in seconds, before ping exits regardless of how
6952    many packets have been received.
6953
6954*-v*
6955    Verbose output.  ICMP packets other than ECHO_RESPONSE that are
6956    received are listed.
6957
6958*-W waittime*
6959    Time in milliseconds to wait for a reply for each packet sent.  If a
6960    reply arrives later, the packet is not printed as replied, but
6961    considered as replied when calculating statistics.
6962
6963*-z tos*
6964    Use the specified type of service.
6965
6966**EXIT STATUS:**
6967
6968The ping utility exits with one of the following values:
6969
69700    At least one response was heard from the specified host.
6971
69722    The transmission was successful but no responses were
6973received.
6974
6975any other value an error occurred.  These values are defined in
6976<sysexits.h>.
6977
6978**NOTES:**
6979
6980When using ping for fault isolation, it should first be run on the
6981local host, to verify that the local network interface is up and
6982running.  Then, hosts and gateways further and further away should be
6983“pinged”.  Round-trip times and packet loss statistics are computed.
6984If duplicate packets are received, they are not included in the packet
6985loss calculation, although the round trip time of these packets is
6986used in calculating the round-trip time statistics.  When the
6987specified number of packets have been sent a brief summary is
6988displayed, showing the number of packets sent and received, and the
6989minimum, mean, maximum, and standard deviation of the round-trip
6990times.
6991
6992This program is intended for use in network testing, measurement and
6993management.  Because of the load it can impose on the network, it is
6994unwise to use ping during normal operations or from automated scripts.
6995
6996**EXAMPLES:**
6997
6998The following is an example of how to use ``oing`` to ping:
6999.. code:: c
7000
7001    [/] # ping 10.10.10.1
7002    PING 10.10.10.1 (10.10.10.1): 56 data bytes
7003    64 bytes from 10.10.10.1: icmp_seq=0 ttl=63 time=0.356 ms
7004    64 bytes from 10.10.10.1: icmp_seq=1 ttl=63 time=0.229 ms
7005    64 bytes from 10.10.10.1: icmp_seq=2 ttl=63 time=0.233 ms
7006    64 bytes from 10.10.10.1: icmp_seq=3 ttl=63 time=0.235 ms
7007    64 bytes from 10.10.10.1: icmp_seq=4 ttl=63 time=0.229 ms
7008    --- 10.10.10.1 ping statistics ---
7009    5 packets transmitted, 5 packets received, 0.0% packet loss
7010    round-trip min/avg/max/stddev = 0.229/0.256/0.356/0.050 ms
7011    \[/] # ping -f -c 10000  10.10.10.1
7012    PING 10.10.10.1 (10.10.10.1): 56 data bytes
7013    .
7014    --- 10.10.10.1 ping statistics ---
7015    10000 packets transmitted, 10000 packets received, 0.0% packet loss
7016    round-trip min/avg/max/stddev = 0.154/0.225/0.533/0.027 ms
7017
7018**CONFIGURATION:**
7019
7020.. index:: CONFIGURE_SHELL_NO_COMMAND_PING
7021.. index:: CONFIGURE_SHELL_COMMAND_PING
7022
7023This command is included in the default shell command set.
7024When building a custom command set, define``CONFIGURE_SHELL_COMMAND_PING`` to have this
7025command included.
7026
7027This command can be excluded from the shell command set by
7028defining ``CONFIGURE_SHELL_NO_COMMAND_PING`` when all
7029shell commands have been configured.
7030
7031**PROGRAMMING INFORMATION:**
7032
7033.. index:: rtems_shell_rtems_main_ping
7034
7035The ``ping`` is implemented by a C language function
7036which has the following prototype:
7037.. code:: c
7038
7039    int rtems_shell_rtems_main_ping(
7040    int    argc,
7041    char \**argv
7042    );
7043
7044The configuration structure for the ``ping`` has the
7045following prototype:
7046.. code:: c
7047
7048    extern rtems_shell_cmd_t rtems_shell_PING_Command;
7049
7050Function and Variable Index
7051###########################
7052
7053.. COMMENT: There are currently no Command and Variable Index entries.
7054
7055Concept Index
7056#############
7057
7058Command Index
7059#############
7060
Note: See TracBrowser for help on using the repository browser.