Changeset 010f96f in rtems


Ignore:
Timestamp:
May 13, 2010, 3:45:02 AM (9 years ago)
Author:
Chris Johns <chrisj@…>
Branches:
4.10, 4.11, master
Children:
e9e7552
Parents:
29328f7a
Message:

2010-05-13 Chris Johns <chrisj@…>

  • shell/file.t: Add dd, debugrfs, hexdump, ln, mknod, mkrfs, mv.
  • shell/general.t: Add time.
Location:
doc
Files:
3 edited

Legend:

Unmodified
Added
Removed
  • doc/ChangeLog

    r29328f7a r010f96f  
     12010-05-13      Chris Johns <chrisj@rtems.org>
     2
     3        * shell/file.t: Add dd, debugrfs, hexdump, ln, mknod, mkrfs, mv.
     4        * shell/general.t: Add time.
     5       
    162010-05-12      Sebastian Huber <sebastian.huber@embedded-brains.de>
    27
  • doc/shell/file.t

    r29328f7a r010f96f  
    1717@item @code{umask} - Set file mode creation mask
    1818@item @code{cp} - copy files
     19@item @code{mv} - move files
    1920@item @code{pwd} - print work directory
    2021@item @code{ls} - list files in the directory
     
    2223@item @code{mkdir} - create a directory
    2324@item @code{rmdir} - remove empty directories
     25@item @code{ln} - make links
     26@item @code{mknod} - make device special file
    2427@item @code{chroot} - change the root directory
    2528@item @code{chmod} - change permissions of a file
     
    3033@item @code{unmount} - unmount disk
    3134@item @code{blksync} - sync the block driver
     35@item @code{dd} - format disks
     36@item @code{hexdump} - format disks
    3237@item @code{fdisk} - format disks
    3338@item @code{dir} - alias for ls
     39@item @code{mkrfs} - format RFS file system
    3440@item @code{cd} - alias for chdir
    3541
     
    130136@example
    131137cp [-R [-H | -L | -P]] [-f | -i] [-pv] src target
    132 
    133138cp [-R [-H | -L] ] [-f | -i] [-NpPv] source_file ... target_directory
    134139@end example
     
    146151@table @b
    147152@item -f
    148 
    149153For each existing destination pathname, attempt to overwrite it. If permissions
    150154do not allow copy to succeed, remove it and create a new file, without
     
    153157
    154158@item -H
    155 
    156159If the -R option is specified, symbolic links on the command line are followed.
    157160(Symbolic links encountered in the tree traversal are not followed.)
    158161
    159162@item -i
    160 
    161163Causes cp to write a prompt to the standard error output before copying a file
    162164that would overwrite an existing file. If the response from the standard input
     
    164166
    165167@item -L
    166 
    167168If the -R option is specified, all symbolic links are followed.
    168169
    169170@item -N
    170 
    171171When used with -p, do not copy file flags.
    172172
    173173@item -P
    174 
    175174No symbolic links are followed.
    176175
    177176@item -p
    178 
    179177Causes cp to preserve in the copy as many of the modification time, access
    180178time, file flags, file mode, user ID, and group ID as allowed by permissions.
     
    192190
    193191@item -R
    194 
    195192If source_file designates a directory, cp copies the directory and the entire
    196193subtree connected at that point. This option also causes symbolic links to be
     
    200197
    201198@item -v
    202 
    203199Cause cp to be verbose, showing files as they are copied.
    204200
     
    295291@findex rtems_shell_rtems_main_cp
    296292
    297 The @code{cp} is implemented by a C language function
    298 which has the following prototype:
     293The @code{cp} command is implemented by a C language function which
     294has the following prototype:
    299295
    300296@example
     
    316312The implementation and portions of the documentation for this
    317313command are from NetBSD 4.0.
     314
     315@c
     316@c
     317@c
     318@page
     319@subsection mv - move files
     320
     321@pgindex mv
     322
     323@subheading SYNOPSYS:
     324
     325@example
     326mv [-fiv] source_file target_file
     327mv [-fiv] source_file... target_file
     328@end example
     329
     330@subheading DESCRIPTION:
     331
     332In its first form, the mv utility renames the file named by the source
     333operand to the destination path named by the target operand.  This
     334form is assumed when the last operand does not name an already
     335existing directory.
     336
     337In its second form, mv moves each file named by a source operand to a
     338destination file in the existing directory named by the directory
     339operand.  The destination path for each operand is the pathname
     340produced by the concatenation of the last operand, a slash, and the
     341final pathname component of the named file.
     342
     343The following options are available:
     344
     345@table @b
     346@item -f
     347Do not prompt for confirmation before overwriting the destination
     348path.
     349
     350@item -i
     351Causes mv to write a prompt to standard error before moving a file
     352that would overwrite an existing file.  If the response from the
     353standard input begins with the character 'y', the move is attempted.
     354
     355@item -v
     356Cause mv to be verbose, showing files as they are processed.
     357
     358@end table
     359
     360The last of any -f or -i options is the one which affects mv's
     361behavior.
     362
     363It is an error for any of the source operands to specify a nonexistent
     364file or directory.
     365
     366It is an error for the source operand to specify a directory if the
     367target exists and is not a directory.
     368
     369If the destination path does not have a mode which permits writing, mv
     370prompts the user for confirmation as specified for the -i option.
     371
     372Should the @b{rename} call fail because source and target are on
     373different file systems, @code{mv} will remove the destination file,
     374copy the source file to the destination, and then remove the source.
     375The effect is roughly equivalent to:
     376
     377@example
     378rm -f destination_path && \
     379cp -PRp source_file destination_path && \
     380rm -rf source_file
     381@end example
     382
     383@subheading EXIT STATUS:
     384
     385The @code{mv} utility exits 0 on success, and >0 if an error occurs.
     386
     387@subheading NOTES:
     388
     389NONE
     390
     391@subheading EXAMPLES:
     392
     393@example
     394SHLL [/] mv /dev/console /dev/con1
     395@end example
     396
     397@subheading CONFIGURATION:
     398
     399@findex CONFIGURE_SHELL_NO_COMMAND_MV
     400@findex CONFIGURE_SHELL_COMMAND_MV
     401
     402This command is included in the default shell command set.  When
     403building a custom command set, define
     404@code{CONFIGURE_SHELL_COMMAND_MV} to have this command included.
     405
     406This command can be excluded from the shell command set by
     407defining @code{CONFIGURE_SHELL_NO_COMMAND_MV} when all
     408shell commands have been configured.
     409
     410@subheading PROGRAMMING INFORMATION:
     411
     412@findex rtems_shell_rtems_main_mv
     413
     414The @code{mv} command is implemented by a C language function which
     415has the following prototype:
     416
     417@example
     418int rtems_shell_rtems_main_mv(
     419  int    argc,
     420  char **argv
     421);
     422@end example
     423
     424The configuration structure for the @code{mv} has the
     425following prototype:
     426
     427@example
     428extern rtems_shell_cmd_t rtems_shell_MV_Command;
     429@end example
     430
     431@subheading ORIGIN:
     432
     433The implementation and portions of the documentation for this command
     434are from NetBSD 4.0.
    318435
    319436@c
     
    710827extern rtems_shell_cmd_t rtems_shell_RMDIR_Command;
    711828@end example
     829
     830@c
     831@c
     832@c
     833@page
     834@subsection ln - make links
     835
     836@pgindex ln
     837
     838@subheading SYNOPSYS:
     839
     840@example
     841ln [-fhinsv] source_file [target_file]
     842ln [-fhinsv] source_file ... target_dir
     843@end example
     844
     845@subheading DESCRIPTION:
     846
     847The ln utility creates a new directory entry (linked file) which has
     848the same modes as the original file.  It is useful for maintaining
     849multiple copies of a file in many places at once without using up
     850storage for the ``copies''; instead, a link ``points'' to the original
     851copy.  There are two types of links; hard links and symbolic links.
     852How a link ``points'' to a file is one of the differences between a
     853hard or symbolic link.
     854
     855The options are as follows:
     856@table @b
     857@item -f
     858Unlink any already existing file, permitting the link to occur.
     859
     860@item -h
     861If the target_file or target_dir is a symbolic link, do not follow it.
     862This is most useful with the -f option, to replace a symlink which may
     863point to a directory.
     864
     865@item -i
     866Cause ln to write a prompt to standard error if the target file
     867exists.  If the response from the standard input begins with the
     868character `y' or `Y', then unlink the target file so that the link may
     869occur.  Otherwise, do not attempt the link.  (The -i option overrides
     870any previous -f options.)
     871
     872@item -n
     873Same as -h, for compatibility with other ln implementations.
     874
     875@item -s
     876Create a symbolic link.
     877
     878@item -v
     879Cause ln to be verbose, showing files as they are processed.
     880@end table
     881
     882By default ln makes hard links.  A hard link to a file is
     883indistinguishable from the original directory entry; any changes to a
     884file are effective independent of the name used to reference the file.
     885Hard links may not normally refer to directories and may not span file
     886systems.
     887
     888A symbolic link contains the name of the file to which it is linked.
     889The referenced file is used when an @i{open} operation is performed on
     890the link.  A @i{stat} on a symbolic link will return the linked-to
     891file; an @i{lstat} must be done to obtain information about the link.
     892The @i{readlink} call may be used to read the contents of a symbolic
     893link.  Symbolic links may span file systems and may refer to
     894directories.
     895
     896Given one or two arguments, ln creates a link to an existing file
     897source_file.  If target_file is given, the link has that name;
     898target_file may also be a directory in which to place the link;
     899otherwise it is placed in the current directory.  If only the
     900directory is specified, the link will be made to the last component of
     901source_file.
     902
     903Given more than two arguments, ln makes links in target_dir to all the
     904named source files.  The links made will have the same name as the
     905files being linked to.
     906
     907@subheading EXIT STATUS:
     908
     909The @code{ln} utility exits 0 on success, and >0 if an error occurs.
     910
     911@subheading NOTES:
     912
     913NONE
     914
     915@subheading EXAMPLES:
     916
     917@example
     918SHLL [/] ln -s /dev/console /dev/con1
     919@end example
     920
     921@subheading CONFIGURATION:
     922
     923@findex CONFIGURE_SHELL_NO_COMMAND_LN
     924@findex CONFIGURE_SHELL_COMMAND_LN
     925
     926This command is included in the default shell command set.  When
     927building a custom command set, define
     928@code{CONFIGURE_SHELL_COMMAND_LN} to have this command included.
     929
     930This command can be excluded from the shell command set by
     931defining @code{CONFIGURE_SHELL_NO_COMMAND_LN} when all
     932shell commands have been configured.
     933
     934@subheading PROGRAMMING INFORMATION:
     935
     936@findex rtems_shell_rtems_main_ln
     937
     938The @code{ln} command is implemented by a C language function which
     939has the following prototype:
     940
     941@example
     942int rtems_shell_rtems_main_ln(
     943  int    argc,
     944  char **argv
     945);
     946@end example
     947
     948The configuration structure for the @code{ln} has the following
     949prototype:
     950
     951@example
     952extern rtems_shell_cmd_t rtems_shell_LN_Command;
     953@end example
     954
     955@subheading ORIGIN:
     956
     957The implementation and portions of the documentation for this command
     958are from NetBSD 4.0.
     959
     960@c
     961@c
     962@c
     963@page
     964@subsection mknod - make device special file
     965
     966@pgindex mknod
     967
     968@subheading SYNOPSYS:
     969
     970@example
     971mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b]
     972      [driver | major] minor
     973mknod [-rR] [-F fmt] [-g gid] [-m mode] [-u uid] name [c | b]
     974      major unit subunit
     975mknod [-rR] [-g gid] [-m mode] [-u uid] name [c | b] number
     976mknod [-rR] [-g gid] [-m mode] [-u uid] name p
     977@end example
     978
     979@subheading DESCRIPTION:
     980
     981The mknod command creates device special files, or fifos.  Normally
     982the shell script /dev/MAKEDEV is used to create special files for
     983commonly known devices; it executes mknod with the appropriate
     984arguments and can make all the files required for the device.
     985
     986To make nodes manually, the arguments are:
     987
     988@table @b
     989@item -r
     990Replace an existing file if its type is incorrect.
     991
     992@item -R
     993Replace an existing file if its type is incorrect.  Correct the
     994mode, user and group.
     995
     996@item -g gid
     997Specify the group for the device node.  The gid operand may be a
     998numeric group ID or a group name.  If a group name is also a numeric
     999group ID, the operand is used as a group name.  Precede a numeric
     1000group ID with a # to stop it being treated as a name.
     1001
     1002@item -m mode
     1003Specify the mode for the device node.  The mode may be absolute or
     1004symbolic, see @i{chmod}.
     1005
     1006@item -u uid
     1007Specify the user for the device node.  The uid operand may be a
     1008numeric user ID or a user name.  If a user name is also a numeric user
     1009ID, the operand is used as a user name.  Precede a numeric user ID
     1010with a # to stop it being treated as a name.
     1011
     1012@item name
     1013Device name, for example ``tty'' for a termios serial device or ``hd''
     1014for a disk.
     1015
     1016@item  b | c | p
     1017Type of device.  If the device is a block type device such as a tape
     1018or disk drive which needs both cooked and raw special files, the type
     1019is b.  All other devices are character type devices, such as terminal
     1020and pseudo devices, and are type c.  Specifying p creates fifo files.
     1021
     1022@item driver | major
     1023The major device number is an integer number which tells the kernel
     1024which device driver entry point to use.  If the device driver is
     1025configured into the current kernel it may be specified by driver name
     1026or major number.
     1027
     1028@item minor
     1029The minor device number tells the kernel which one of several similar
     1030devices the node corresponds to; for example, it may be a specific
     1031serial port or pty.
     1032
     1033@item unit and subunit
     1034The unit and subunit numbers select a subset of a device; for example,
     1035the unit may specify a particular disk, and the subunit a partition on
     1036that disk.  (Currently this form of specification is only supported
     1037by the bsdos format, for compatibility with the BSD/OS mknod).
     1038
     1039@item number
     1040A single opaque device number.  Useful for netbooted computers which
     1041require device numbers packed in a format that isn't supported by
     1042-F.
     1043@end table
     1044
     1045@subheading EXIT STATUS:
     1046
     1047The @code{mknod} utility exits 0 on success, and >0 if an error occurs.
     1048
     1049@subheading NOTES:
     1050
     1051NONE
     1052
     1053@subheading EXAMPLES:
     1054
     1055@example
     1056SHLL [/] mknod c 3 0 /dev/ttyS10
     1057@end example
     1058
     1059@subheading CONFIGURATION:
     1060
     1061@findex CONFIGURE_SHELL_NO_COMMAND_MKNOD
     1062@findex CONFIGURE_SHELL_COMMAND_MKNOD
     1063
     1064This command is included in the default shell command set.  When
     1065building a custom command set, define
     1066@code{CONFIGURE_SHELL_COMMAND_MKNOD} to have this command included.
     1067
     1068This command can be excluded from the shell command set by
     1069defining @code{CONFIGURE_SHELL_NO_COMMAND_MKNOD} when all
     1070shell commands have been configured.
     1071
     1072@subheading PROGRAMMING INFORMATION:
     1073
     1074@findex rtems_shell_rtems_main_mknod
     1075
     1076The @code{mknod} command is implemented by a C language function which
     1077has the following prototype:
     1078
     1079@example
     1080int rtems_shell_rtems_main_mknod(
     1081  int    argc,
     1082  char **argv
     1083);
     1084@end example
     1085
     1086The configuration structure for the @code{mknod} has the following
     1087prototype:
     1088
     1089@example
     1090extern rtems_shell_cmd_t rtems_shell_MKNOD_Command;
     1091@end example
     1092
     1093@subheading ORIGIN:
     1094
     1095The implementation and portions of the documentation for this command
     1096are from NetBSD 4.0.
    7121097
    7131098@c
     
    10731458@item ftp   - FTP Network File System
    10741459@item nfs   - Network File System
     1460@item rfs   - RTEMS File System
    10751461@end itemize
    10761462
    1077 When the file system type is 'msdos' the driver is a "block device driver"
    1078 node present in the file system. The driver is ignored with the 'tftp' and
    1079 'ftp' file systems. For the 'nfs' file system the driver is the 'host:/path'
    1080 string that described NFS host and the exported file system path.
     1463When the file system type is 'msdos' or 'rfs' the driver is a "block
     1464device driver" node present in the file system. The driver is ignored
     1465with the 'tftp' and 'ftp' file systems. For the 'nfs' file system the
     1466driver is the 'host:/path' string that described NFS host and the
     1467exported file system path.
    10811468
    10821469@subheading EXIT STATUS:
     
    10981485
    10991486@example
    1100 $ mount -t msdos /dev/flashdisk0 /fd
     1487SHLL [/] $ mount -t msdos /dev/flashdisk0 /fd
    11011488@end example
    11021489
     
    11181505$ cat /tftp/10.10.10.10/test.txt
    11191506@end example
    1120 
    11211507
    11221508@subheading CONFIGURATION:
     
    11431529@item ftp - CONFIGURE_SHELL_MOUNT_FTP
    11441530@item nfs - CONFIGURE_SHELL_MOUNT_NFS
     1531@item rfs - CONFIGURE_SHELL_MOUNT_RFS
    11451532@end itemize
    11461533
     
    11531540  #define CONFIGURE_SHELL_MOUNT_FTP
    11541541  #define CONFIGURE_SHELL_MOUNT_NFS
     1542  #define CONFIGURE_SHELL_MOUNT_RFS
    11551543#endif
    11561544@end example
     
    13131701@example
    13141702extern rtems_shell_cmd_t rtems_shell_BLKSYNC_Command;
     1703@end example
     1704
     1705@c
     1706@c
     1707@c
     1708@page
     1709@subsection dd - convert and copy a file
     1710
     1711@pgindex dd
     1712
     1713@subheading SYNOPSYS:
     1714
     1715@example
     1716dd [operands ...]
     1717@end example
     1718
     1719@subheading DESCRIPTION:
     1720
     1721The dd utility copies the standard input to the standard output.
     1722Input data is read and written in 512-byte blocks.  If input reads are
     1723short, input from multiple reads are aggregated to form the output
     1724block.  When finished, dd displays the number of complete and partial
     1725input and output blocks and truncated input records to the standard
     1726error output.
     1727
     1728The following operands are available:
     1729
     1730@table @b
     1731@item bs=n
     1732Set both input and output block size, superseding the ibs and obs
     1733operands.  If no conversion values other than noerror, notrunc or sync
     1734are specified, then each input block is copied to the output as a
     1735single block without any aggregation of short blocks.
     1736
     1737@item cbs=n
     1738Set the conversion record size to n bytes.  The conversion record size
     1739is required by the record oriented conversion values.
     1740
     1741@item count=n
     1742Copy only n input blocks.
     1743
     1744@item files=n
     1745Copy n input files before terminating.  This operand is only
     1746applicable when the input device is a tape.
     1747
     1748@item ibs=n
     1749Set the input block size to n bytes instead of the default 512.
     1750
     1751@item if=file
     1752Read input from file instead of the standard input.
     1753
     1754@item obs=n
     1755Set the output block size to n bytes instead of the default 512.
     1756
     1757@item of=file
     1758Write output to file instead of the standard output.  Any regular
     1759output file is truncated unless the notrunc conversion value is
     1760specified.  If an initial portion of the output file is skipped (see
     1761the seek operand) the output file is truncated at that point.
     1762
     1763@item seek=n
     1764Seek n blocks from the beginning of the output before copying.  On
     1765non-tape devices, a @i{lseek} operation is used.  Otherwise, existing
     1766blocks are read and the data discarded.  If the seek operation is past
     1767the end of file, space from the current end of file to the specified
     1768offset is filled with blocks of NUL bytes.
     1769
     1770@item skip=n
     1771Skip n blocks from the beginning of the input before copying.  On
     1772input which supports seeks, a @i{lseek} operation is used.  Otherwise,
     1773input data is read and discarded.  For pipes, the correct number of
     1774bytes is read.  For all other devices, the correct number of blocks is
     1775read without distinguishing between a partial or complete block being
     1776read.
     1777
     1778@item progress=n
     1779Switch on display of progress if n is set to any non-zero value.  This
     1780will cause a ``.'' to be printed (to the standard error output) for
     1781every n full or partial blocks written to the output file.
     1782
     1783@item conv=value[,value...]
     1784Where value is one of the symbols from the following list.
     1785
     1786@table @b
     1787@item ascii, oldascii
     1788The same as the unblock value except that characters are translated
     1789from EBCDIC to ASCII before the records are converted.  (These values
     1790imply unblock if the operand cbs is also specified.)  There are two
     1791conversion maps for ASCII.  The value ascii specifies the recom-
     1792mended one which is compatible with AT&T System V UNIX.  The value
     1793oldascii specifies the one used in historic AT&T and pre 4.3BSD-Reno
     1794systems.
     1795
     1796@item block
     1797Treats the input as a sequence of newline or end-of-file terminated
     1798variable length records independent of input and output block
     1799boundaries.  Any trailing newline character is discarded.  Each
     1800input record is converted to a fixed length output record where the
     1801length is specified by the cbs operand.  Input records shorter than
     1802the conversion record size are padded with spaces.  Input records
     1803longer than the conversion record size are truncated.  The number of
     1804truncated input records, if any, are reported to the standard error
     1805output at the completion of the copy.
     1806
     1807@item ebcdic, ibm, oldebcdic, oldibm
     1808The same as the block value except that characters are translated from
     1809ASCII to EBCDIC after the records are converted.  (These values imply
     1810block if the operand cbs is also specified.)  There are four
     1811conversion maps for EBCDIC.  The value ebcdic specifies the
     1812recommended one which is compatible with AT&T System V UNIX.  The
     1813value ibm is a slightly different mapping, which is compatible with
     1814the AT&T System V UNIX ibm value.  The values oldebcdic and oldibm are
     1815maps used in historic AT&T and pre 4.3BSD-Reno systems.
     1816
     1817@item lcase
     1818Transform uppercase characters into lowercase characters.
     1819
     1820@item noerror
     1821Do not stop processing on an input error.  When an input error occurs,
     1822a diagnostic message followed by the current input and output block
     1823counts will be written to the standard error output in the same format
     1824as the standard completion message.  If the sync conversion is also
     1825specified, any missing input data will be replaced with NUL bytes (or
     1826with spaces if a block oriented conversion value was specified) and
     1827processed as a normal input buffer.  If the sync conversion is not
     1828specified, the input block is omitted from the output.  On input files
     1829which are not tapes or pipes, the file offset will be positioned past
     1830the block in which the error occurred using lseek(2).
     1831
     1832@item notrunc
     1833Do not truncate the output file.  This will preserve any blocks in the
     1834output file not explicitly written by dd.  The notrunc value is not
     1835supported for tapes.
     1836
     1837@item osync
     1838Pad the final output block to the full output block size.  If the
     1839input file is not a multiple of the output block size after
     1840conversion, this conversion forces the final output block to be the
     1841same size as preceding blocks for use on devices that require
     1842regularly sized blocks to be written.  This option is incompatible
     1843with use of the bs=n block size specification.
     1844
     1845@item sparse
     1846If one or more non-final output blocks would consist solely of NUL
     1847bytes, try to seek the output file by the required space instead of
     1848filling them with NULs.  This results in a sparse file on some file
     1849systems.
     1850
     1851@item swab
     1852Swap every pair of input bytes.  If an input buffer has an odd number
     1853of bytes, the last byte will be ignored during swapping.
     1854
     1855@item sync
     1856Pad every input block to the input buffer size.  Spaces are used for
     1857pad bytes if a block oriented conversion value is specified, otherwise
     1858NUL bytes are used.
     1859
     1860@item ucase
     1861Transform lowercase characters into uppercase characters.
     1862
     1863@item unblock
     1864Treats the input as a sequence of fixed length records independent of
     1865input and output block boundaries.  The length of the input records is
     1866specified by the cbs operand.  Any trailing space characters are
     1867discarded and a newline character is appended.
     1868@end table
     1869@end table
     1870
     1871Where sizes are specified, a decimal number of bytes is expected.  Two
     1872or more numbers may be separated by an ``x'' to indicate a product.
     1873Each number may have one of the following optional suffixes:
     1874@table @b
     1875@item b
     1876Block; multiply by 512
     1877@item k
     1878Kibi; multiply by 1024 (1 KiB)
     1879@item m
     1880Mebi; multiply by 1048576 (1 MiB)
     1881@item g
     1882Gibi; multiply by 1073741824 (1 GiB)
     1883@item t
     1884Tebi; multiply by 1099511627776 (1 TiB)
     1885@item w
     1886Word; multiply by the number of bytes in an integer
     1887@end table
     1888
     1889When finished, dd displays the number of complete and partial input
     1890and output blocks, truncated input records and odd-length
     1891byte-swapping ritten.  Partial output blocks to tape devices are
     1892considered fatal errors.  Otherwise, the rest of the block will be
     1893written.  Partial output blocks to character devices will produce a
     1894warning message.  A truncated input block is one where a variable
     1895length record oriented conversion value was specified and the input
     1896line was too long to fit in the conversion record or was not newline
     1897terminated.
     1898
     1899Normally, data resulting from input or conversion or both are
     1900aggregated into output blocks of the specified size.  After the end of
     1901input is reached, any remaining output is written as a block.  This
     1902means that the final output block may be shorter than the output block
     1903size.
     1904
     1905@subheading EXIT STATUS:
     1906
     1907This command returns 0 on success and non-zero if an error is encountered.
     1908
     1909@subheading NOTES:
     1910
     1911NONE
     1912
     1913@subheading EXAMPLES:
     1914
     1915The following is an example of how to use @code{dd}:
     1916
     1917@example
     1918SHLL [/] $ dd if=/nfs/boot-image of=/dev/hda1
     1919@end example
     1920
     1921@subheading CONFIGURATION:
     1922
     1923@findex CONFIGURE_SHELL_NO_COMMAND_DD
     1924@findex CONFIGURE_SHELL_COMMAND_DD
     1925
     1926This command is included in the default shell command set.  When
     1927building a custom command set, define
     1928@code{CONFIGURE_SHELL_COMMAND_DD} to have this command included.
     1929
     1930This command can be excluded from the shell command set by defining
     1931@code{CONFIGURE_SHELL_NO_COMMAND_DD} when all shell commands have been
     1932configured.
     1933
     1934@subheading PROGRAMMING INFORMATION:
     1935
     1936@findex rtems_shell_rtems_main_dd
     1937
     1938The @code{dd} command is implemented by a C language function which
     1939has the following prototype:
     1940
     1941@example
     1942int rtems_shell_rtems_main_dd(
     1943  int    argc,
     1944  char **argv
     1945);
     1946@end example
     1947
     1948The configuration structure for the @code{dd} has the following
     1949prototype:
     1950
     1951@example
     1952extern rtems_shell_cmd_t rtems_shell_DD_Command;
     1953@end example
     1954
     1955@c
     1956@c
     1957@c
     1958@page
     1959@subsection hexdump - ascii/dec/hex/octal dump
     1960
     1961@pgindex hexdump
     1962
     1963@subheading SYNOPSYS:
     1964
     1965@example
     1966hexdump [-bcCdovx] [-e format_string] [-f format_file] [-n length]
     1967        [-s skip] file ...
     1968@end example
     1969
     1970@subheading DESCRIPTION:
     1971
     1972The hexdump utility is a filter which displays the specified files, or
     1973the standard input, if no files are specified, in a user specified
     1974format.
     1975
     1976The options are as follows:
     1977
     1978@table @b
     1979@item -b
     1980One-byte octal display.  Display the input offset in hexadecimal,
     1981followed by sixteen space-separated, three column, zero-filled, bytes
     1982of input data, in octal, per line.
     1983
     1984@item -c
     1985One-byte character display.  Display the input offset in hexadecimal,
     1986followed by sixteen space-separated, three column, space-filled,
     1987characters of input data per line.
     1988
     1989@item -C
     1990Canonical hex+ASCII display.  Display the input offset in hexadecimal,
     1991followed by sixteen space-separated, two column, hexadecimal bytes,
     1992followed by the same sixteen bytes in %_p format enclosed in ``|''
     1993characters.
     1994
     1995@item -d
     1996Two-byte decimal display.  Display the input offset in hexadecimal,
     1997followed by eight space-separated, five column, zero-filled, two-byte
     1998units of input data, in unsigned decimal, per line.
     1999
     2000@item -e format_string
     2001Specify a format string to be used for displaying data.
     2002
     2003@item -f format_file
     2004Specify a file that contains one or more newline separated format
     2005strings.  Empty lines and lines whose first non-blank character is a
     2006hash mark (#) are ignored.
     2007
     2008@item -n length
     2009Interpret only length bytes of input.
     2010
     2011@item -o
     2012Two-byte octal display.  Display the input offset in hexadecimal,
     2013followed by eight space-separated, six column, zerofilled, two byte
     2014quantities of input data, in octal, per line.
     2015
     2016@item -s offset
     2017Skip offset bytes from the beginning of the input.  By default, offset
     2018is interpreted as a decimal number.  With a leading 0x or 0X, offset
     2019is interpreted as a hexadecimal number, otherwise, with a leading 0,
     2020offset is interpreted as an octal number.  Appending the character b,
     2021k, or m to offset causes it to be interpreted as a multiple of 512,
     20221024, or 1048576, respectively.
     2023
     2024@item -v
     2025The -v option causes hexdump to display all input data.  Without the
     2026-v option, any number of groups of output lines, which would be
     2027identical to the immediately preceding group of output lines (except
     2028for the input offsets), are replaced with a line containing a single
     2029asterisk.
     2030
     2031@item -x
     2032Two-byte hexadecimal display.  Display the input offset in
     2033hexadecimal, followed by eight, space separated, four column,
     2034zero-filled, two-byte quantities of input data, in hexadecimal, per
     2035line.
     2036@end table
     2037
     2038For each input file, hexdump sequentially copies the input to standard
     2039output, transforming the data according to the format strings
     2040specified by the -e and -f options, in the order that they were
     2041specified.
     2042
     2043@b{Formats}
     2044
     2045A format string contains any number of format units, separated by
     2046whitespace.  A format unit contains up to three items: an iteration
     2047count, a byte count, and a format.
     2048
     2049The iteration count is an optional positive integer, which defaults to
     2050one.  Each format is applied iteration count times.
     2051
     2052The byte count is an optional positive integer.  If specified it
     2053defines the number of bytes to be interpreted by each iteration of the
     2054format.
     2055
     2056If an iteration count and/or a byte count is specified, a single slash
     2057must be placed after the iteration count and/or before the byte count
     2058to disambiguate them.  Any whitespace before or after the slash is
     2059ignored.
     2060
     2061The format is required and must be surrounded by double quote (`` ``)
     2062marks.  It is interpreted as a fprintf-style format string (see
     2063@i{fprintf}), with the following exceptions:
     2064
     2065@itemize @bullet
     2066@item
     2067An asterisk (*) may not be used as a field width or precision.
     2068@item
     2069A byte count or field precision is required for each ``s'' con-
     2070version character (unlike the fprintf(3) default which prints the
     2071entire string if the precision is unspecified).
     2072@item
     2073The conversion characters ``h'', ``l'', ``n'', ``p'' and ``q'' are not
     2074supported.
     2075@item
     2076The single character escape sequences described in the C standard
     2077are supported:
     2078@quotation
     2079NUL                  \0
     2080<alert character>    \a
     2081<backspace>          \b
     2082<form-feed>          \f
     2083<newline>            \n
     2084<carriage return>    \r
     2085<tab>                \t
     2086<vertical tab>       \v
     2087@end quotation
     2088@end itemize
     2089
     2090Hexdump also supports the following additional conversion strings:
     2091
     2092@table @b
     2093@item _a[dox]
     2094Display the input offset, cumulative across input files, of the next
     2095byte to be displayed.  The appended characters d, o, and x specify the
     2096display base as decimal, octal or hexadecimal respectively.
     2097
     2098@item _A[dox]
     2099Identical to the _a conversion string except that it is only performed
     2100once, when all of the input data has been processed.
     2101
     2102@item _c
     2103Output characters in the default character set.  Nonprinting
     2104characters are displayed in three character, zero-padded octal, except
     2105for those representable by standard escape notation (see above), which
     2106are displayed as two character strings.
     2107
     2108@item _p
     2109Output characters in the default character set.  Nonprinting
     2110characters are displayed as a single ``.''.
     2111
     2112@item _u
     2113Output US ASCII characters, with the exception that control characters
     2114are displayed using the following, lower-case, names.  Characters
     2115greater than 0xff, hexadecimal, are displayed as hexadecimal
     2116strings.
     2117
     2118000 nul  001 soh  002 stx  003 etx  004 eot  005 enq
     2119006 ack  007 bel  008 bs   009 ht   00A lf   00B vt
     212000C ff   00D cr   00E so   00F si   010 dle  011 dc1
     2121012 dc2  013 dc3  014 dc4  015 nak  016 syn  017 etb
     2122018 can  019 em   01A sub  01B esc  01C fs   01D gs
     212301E rs   01F us   07F del
     2124@end table
     2125
     2126The default and supported byte counts for the conversion characters
     2127are as follows:
     2128
     2129@quotation
     2130%_c, %_p, %_u, %c       One byte counts only.
     2131
     2132%d, %i, %o, %u, %X, %x  Four byte default, one, two, four
     2133                        and eight byte counts supported.
     2134
     2135%E, %e, %f, %G, %g      Eight byte default, four byte
     2136                        counts supported.
     2137@end quotation
     2138
     2139The amount of data interpreted by each format string is the sum of the
     2140data required by each format unit, which is the iteration count times
     2141the byte count, or the iteration count times the number of bytes
     2142required by the format if the byte count is not specified.
     2143
     2144The input is manipulated in ``blocks'', where a block is defined as
     2145the largest amount of data specified by any format string.  Format
     2146strings interpreting less than an input block's worth of data, whose
     2147last format unit both interprets some number of bytes and does not
     2148have a specified iteration count, have the iteration count incremented
     2149until the entire input block has been processed or there is not enough
     2150data remaining in the block to satisfy the format string.
     2151
     2152If, either as a result of user specification or hexdump modifying the
     2153iteration count as described above, an iteration count is greater than
     2154one, no trailing whitespace characters are output during the last
     2155iteration.
     2156
     2157It is an error to specify a byte count as well as multiple conversion
     2158characters or strings unless all but one of the conversion characters
     2159or strings is _a or _A.
     2160
     2161If, as a result of the specification of the -n option or end-of-file
     2162being reached, input data only partially satisfies a format string,
     2163the input block is zero-padded sufficiently to display all available
     2164data (i.e. any format units overlapping the end of data will display
     2165some num- ber of the zero bytes).
     2166
     2167Further output by such format strings is replaced by an equivalent
     2168number of spaces.  An equivalent number of spaces is defined as the
     2169number of spaces output by an s conversion character with the same
     2170field width and precision as the original conversion character or
     2171conversion string but with any ``+'', `` '', ``#'' conversion flag
     2172characters removed, and ref- erencing a NULL string.
     2173
     2174If no format strings are specified, the default display is equivalent
     2175to specifying the -x option.
     2176
     2177@subheading EXIT STATUS:
     2178
     2179This command returns 0 on success and non-zero if an error is encountered.
     2180
     2181@subheading NOTES:
     2182
     2183NONE
     2184
     2185@subheading EXAMPLES:
     2186
     2187The following is an example of how to use @code{hexdump}:
     2188
     2189@example
     2190SHLL [/] $ hexdump -C -n 512 /dev/hda1
     2191@end example
     2192
     2193@subheading CONFIGURATION:
     2194
     2195@findex CONFIGURE_SHELL_NO_COMMAND_HEXDUMP
     2196@findex CONFIGURE_SHELL_COMMAND_HEXDUMP
     2197
     2198This command is included in the default shell command set.  When
     2199building a custom command set, define
     2200@code{CONFIGURE_SHELL_COMMAND_HEXDUMP} to have this command included.
     2201
     2202This command can be excluded from the shell command set by defining
     2203@code{CONFIGURE_SHELL_NO_COMMAND_HEXDUMP} when all shell commands have
     2204been configured.
     2205
     2206@subheading PROGRAMMING INFORMATION:
     2207
     2208@findex rtems_shell_rtems_main_hexdump
     2209
     2210The @code{hexdump} command is implemented by a C language function
     2211which has the following prototype:
     2212
     2213@example
     2214int rtems_shell_rtems_main_hexdump(
     2215  int    argc,
     2216  char **argv
     2217);
     2218@end example
     2219
     2220The configuration structure for the @code{hexdump} has the following
     2221prototype:
     2222
     2223@example
     2224extern rtems_shell_cmd_t rtems_shell_HEXDUMP_Command;
    13152225@end example
    13162226
     
    14212331@example
    14222332extern rtems_shell_cmd_t rtems_shell_DIR_Command;
     2333@end example
     2334
     2335@c
     2336@c
     2337@c
     2338@page
     2339@subsection mkrfs - format RFS file system
     2340
     2341@pgindex mkrfs
     2342
     2343@subheading SYNOPSYS:
     2344
     2345@example
     2346mkrfs [-vsbiIo] device
     2347@end example
     2348
     2349@subheading DESCRIPTION:
     2350
     2351Format the block device with the RTEMS File System (RFS). The default
     2352configuration with not parameters selects a suitable block size based
     2353on the size of the media being formatted.
     2354
     2355The media is broken up into groups of blocks. The number of blocks in
     2356a group is based on the number of bits a block contains. The large a
     2357block the more blocks a group contains and the fewer groups in the
     2358file system.
     2359
     2360The following options are provided:
     2361
     2362@table @b
     2363@item -v
     2364Display configuration and progress of the format.
     2365
     2366@item -s
     2367Set the block size in bytes.
     2368
     2369@item -b
     2370The number of blocks in a group. The block count must be equal or less
     2371than the number of bits in a block.
     2372
     2373@item -i
     2374Number of inodes in a group. The inode count must be equal or less
     2375than the number of bits in a block.
     2376
     2377@item -I
     2378Initialise the inodes. The default is not to initialise the inodes and
     2379to rely on the inode being initialised when allocated. Initialising
     2380the inode table helps recovery if a problem appears.
     2381
     2382@item -o
     2383Integer percentage of the media used by inodes. The default is 1%.
     2384
     2385@item device
     2386Path of the device to format.
     2387@end table
     2388
     2389@subheading EXIT STATUS:
     2390
     2391This command returns 0 on success and non-zero if an error is encountered.
     2392
     2393@subheading NOTES:
     2394
     2395NONE
     2396
     2397@subheading EXAMPLES:
     2398
     2399The following is an example of how to use @code{mkrfs}:
     2400
     2401@example
     2402SHLL [/] $ mkrfs /dev/fdda
     2403@end example
     2404
     2405@subheading CONFIGURATION:
     2406
     2407@findex CONFIGURE_SHELL_NO_COMMAND_MKRFS
     2408@findex CONFIGURE_SHELL_COMMAND_MKRFS
     2409
     2410This command is included in the default shell command set. 
     2411When building a custom command set, define
     2412@code{CONFIGURE_SHELL_COMMAND_MKRFS} to have this
     2413command included.
     2414
     2415This command can be excluded from the shell command set by
     2416defining @code{CONFIGURE_SHELL_NO_COMMAND_MKRFS} when all
     2417shell commands have been configured.
     2418
     2419@subheading PROGRAMMING INFORMATION:
     2420
     2421@findex rtems_shell_rtems_main_mkrfs
     2422
     2423The @code{mkrfs} command is implemented by a C language function which
     2424has the following prototype:
     2425
     2426@example
     2427int rtems_shell_rtems_main_mkrfs(
     2428  int    argc,
     2429  char **argv
     2430);
     2431@end example
     2432
     2433The configuration structure for @code{mkrfs} has the following
     2434prototype:
     2435
     2436@example
     2437extern rtems_shell_cmd_t rtems_shell_MKRFS_Command;
     2438@end example
     2439
     2440@c
     2441@c
     2442@c
     2443@page
     2444@subsection debugrfs - debug RFS file system
     2445
     2446@pgindex debugrfs
     2447
     2448@subheading SYNOPSYS:
     2449
     2450@example
     2451debugrfs [-hl] path command [options]
     2452@end example
     2453
     2454@subheading DESCRIPTION:
     2455
     2456The command provides debugging information for the RFS file system.
     2457
     2458The options are:
     2459
     2460@table @b
     2461@item -h
     2462Print a help message.
     2463
     2464@item -l
     2465List the commands.
     2466
     2467@item path
     2468Path to the mounted RFS file system. The file system has to be mounted
     2469to view to use this command.
     2470@end table
     2471
     2472The commands are:
     2473
     2474@table @b
     2475@item block start [end]
     2476Display the contents of the blocks from start to end.
     2477
     2478@item data
     2479Display the file system data and configuration.
     2480
     2481@item dir bno
     2482Process the block as a directory displaying the entries.
     2483
     2484@item group start [end]
     2485Display the group data from the start group to the end group.
     2486
     2487@item inode [-aef] [start] [end]
     2488Display the inodes between start and end. If no start and end is
     2489provides all inodes are displayed.
     2490
     2491@table @b
     2492@item -a
     2493Display all inodes. That is allocated and unallocated inodes.
     2494@item -e
     2495Search and display on inodes that have an error.
     2496@item -f
     2497Force display of inodes, even when in error.
     2498@end table
     2499@end table
     2500
     2501@subheading EXIT STATUS:
     2502
     2503This command returns 0 on success and non-zero if an error is encountered.
     2504
     2505@subheading NOTES:
     2506
     2507NONE
     2508
     2509@subheading EXAMPLES:
     2510
     2511The following is an example of how to use @code{debugrfs}:
     2512
     2513@example
     2514SHLL [/] $ debugrfs /c data
     2515@end example
     2516
     2517@subheading CONFIGURATION:
     2518
     2519@findex CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS
     2520@findex CONFIGURE_SHELL_COMMAND_DEBUGRFS
     2521
     2522This command is included in the default shell command set. 
     2523When building a custom command set, define
     2524@code{CONFIGURE_SHELL_COMMAND_DEBUGRFS} to have this
     2525command included.
     2526
     2527This command can be excluded from the shell command set by
     2528defining @code{CONFIGURE_SHELL_NO_COMMAND_DEBUGRFS} when all
     2529shell commands have been configured.
     2530
     2531@subheading PROGRAMMING INFORMATION:
     2532
     2533@findex rtems_shell_rtems_main_debugrfs
     2534
     2535The @code{debugrfs} command is implemented by a C language function which
     2536has the following prototype:
     2537
     2538@example
     2539int rtems_shell_rtems_main_debugrfs(
     2540  int    argc,
     2541  char **argv
     2542);
     2543@end example
     2544
     2545The configuration structure for @code{debugrfs} has the following
     2546prototype:
     2547
     2548@example
     2549extern rtems_shell_cmd_t rtems_shell_DEBUGRFS_Command;
    14232550@end example
    14242551
  • doc/shell/general.t

    r29328f7a r010f96f  
    2525@item @code{setenv} - set environment variable
    2626@item @code{unsetenv} - unset environment variable
     27@item @code{time} - time command execution
    2728@item @code{logoff} - logoff from the system
     29@item @code{rtc} - RTC driver configuration
    2830@item @code{exit} - alias for logoff command
    29 @item @code{rtc} - RTC driver configuration
    3031
    3132@end itemize
     
    844845@c
    845846@page
     847@subsection time - time command execution
     848
     849@pgindex time
     850
     851@subheading SYNOPSYS:
     852
     853@example
     854time command [argument ...]
     855@end example
     856
     857@subheading DESCRIPTION:
     858
     859The time command executes and times a command.  After the command
     860finishes, time writes the total time elapsed.  Times are reported in
     861seconds.
     862
     863@subheading EXIT STATUS:
     864
     865This command returns 0 on success and non-zero if an error is encountered.
     866
     867@subheading NOTES:
     868
     869None.
     870
     871@subheading EXAMPLES:
     872
     873The following is an example of how to use @code{time}:
     874
     875@example
     876SHLL [/] $ time cp -r /nfs/directory /c
     877@end example
     878
     879@subheading CONFIGURATION:
     880
     881@findex CONFIGURE_SHELL_NO_COMMAND_TIME
     882@findex CONFIGURE_SHELL_COMMAND_TIME
     883
     884This command is included in the default shell command set.  When
     885building a custom command set, define
     886@code{CONFIGURE_SHELL_COMMAND_TIME} to have this command included.
     887
     888This command can be excluded from the shell command set by
     889defining @code{CONFIGURE_SHELL_NO_COMMAND_TIME} when all
     890shell commands have been configured.
     891
     892@subheading PROGRAMMING INFORMATION:
     893
     894@findex rtems_shell_rtems_main_time
     895
     896The @code{time} is implemented by a C language function
     897which has the following prototype:
     898
     899@example
     900int rtems_shell_rtems_main_time(
     901  int    argc,
     902  char **argv
     903);
     904@end example
     905
     906The configuration structure for the @code{time} has the
     907following prototype:
     908
     909@example
     910extern rtems_shell_cmd_t rtems_shell_TIME_Command;
     911@end example
     912
     913@c
     914@c
     915@c
     916@page
    846917@subsection logoff - logoff from the system
    847918
     
    917988@c
    918989@page
     990@subsection rtc - RTC driver configuration
     991
     992@pgindex rtc
     993
     994@subheading SYNOPSYS:
     995
     996@example
     997rtc
     998@end example
     999
     1000@subheading CONFIGURATION:
     1001
     1002@findex CONFIGURE_SHELL_NO_COMMAND_RTC
     1003@findex CONFIGURE_SHELL_COMMAND_RTC
     1004
     1005This command is included in the default shell command set. 
     1006When building a custom command set, define
     1007@code{CONFIGURE_SHELL_COMMAND_RTC} to have this
     1008command included.
     1009
     1010This command can be excluded from the shell command set by
     1011defining @code{CONFIGURE_SHELL_NO_COMMAND_RTC} when all
     1012shell commands have been configured.
     1013
     1014@c
     1015@c
     1016@c
     1017@page
    9191018@subsection exit - exit the shell
    9201019
     
    9571056The @code{exit} is implemented directly in the shell interpreter.
    9581057There is no C routine associated with it.
    959 
    960 @c
    961 @c
    962 @c
    963 @page
    964 @subsection rtc - RTC driver configuration
    965 
    966 @pgindex rtc
    967 
    968 @subheading SYNOPSYS:
    969 
    970 @example
    971 rtc
    972 @end example
    973 
    974 @subheading CONFIGURATION:
    975 
    976 @findex CONFIGURE_SHELL_NO_COMMAND_RTC
    977 @findex CONFIGURE_SHELL_COMMAND_RTC
    978 
    979 This command is included in the default shell command set. 
    980 When building a custom command set, define
    981 @code{CONFIGURE_SHELL_COMMAND_RTC} to have this
    982 command included.
    983 
    984 This command can be excluded from the shell command set by
    985 defining @code{CONFIGURE_SHELL_NO_COMMAND_RTC} when all
    986 shell commands have been configured.
Note: See TracChangeset for help on using the changeset viewer.