home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / utlos2.zip / Doc / ls.doc < prev    next >
Text File  |  1998-02-07  |  14KB  |  314 lines
  1. $Id: ls.doc 1.9 1998/02/08 02:00:27 brian Exp $
  2.  
  3.                        ls.doc : The ls command
  4.                           By: Brian E. Yoder.
  5.  
  6.         (c) Copyright International Business Machines Corporation 1998
  7.         All rights reserved.
  8.  
  9. The ls (list directory) command is a loose adaptation of the AIX ls
  10. command, and is a better DIR command than DIR. It supports multiple
  11. file specifications on the command line. It matches filenames using
  12. the AIX Bourne shell pattern matching rules and not the DOS or OS/2
  13. "wildcard" rules. See pattern.doc for a description of filename
  14. matching patterns.
  15.  
  16. The ls command lists the names of ordinary files, hidden files, system
  17. files, and directories as you wish. It also lists each name with any
  18. drive and path information that was in the original file
  19. specification. It can recursively descend subdirectories looking for
  20. matching files and or directories if you wish.
  21.  
  22. In the "long" format, the ls command displays each file's attributes
  23. as well as its size, date, and time.
  24.  
  25. By default, ls sorts the output by filename, and displays the names in
  26. multicolumn format if standard output is a character device, just as
  27. AIX does.
  28.  
  29. These features are found in the Win32, DOS, and OS/2 versions of ls!
  30.  
  31. ========================================================================
  32. Command usage
  33. ========================================================================
  34.  
  35. Invoke the command as follows:
  36.  
  37.         ls [ -flags ] [ -- ] [ fspec ... ]
  38.  
  39. The flags are optional. If specified, they must consist of a dash
  40. followed by one or more contiguous flag characters. The flags control
  41. what names are listed and in what format they are listed.
  42.  
  43. If no flags are specified, then -fdn is assumed: list all matching
  44. ordinary files and directories, and sort them by name.
  45.  
  46. Zero or more file specifications may be entered. Each file
  47. specification consists of an optional drive, optional path, and
  48. filename. Each filename may contain AIX shell pattern-matching
  49. characters (better than DOS's and OS/2's wildcard characters). The ls
  50. command lists all files in the specified directory whose names match
  51. the filename, according to the -flags.
  52.  
  53. If a file specification is that of a directory, then ls appends '\*'
  54. to it and matches everything in that directory. If there are no file
  55. specifications, then ls assumes '*': match everything in the current
  56. directory.
  57.  
  58. The following (case-sensitive) flag characters are supported:
  59.  
  60.     -f  List all ordinary (including readonly) files that match the file
  61.         specification(s). If the f flag is specified, then directories
  62.         are not listed unless the d flag is also specified.
  63.  
  64.     -s  List all system files.
  65.  
  66.     -h  List all hidden files.
  67.  
  68.     -d  List all subdirectories that match the file specification(s). If
  69.         the d flag is specified, then ordinary files are not listed
  70.         unless the f flag is also specified.
  71.  
  72.     -a  List all ordinary files, system files, hidden files, directories,
  73.         the . and .. directories, and, for DOS only, volume ids.
  74.  
  75.     -l  List each matching file or directory name in "long" format. For
  76.         each name, it also displays the attributes, size, time stamp,
  77.         and date stamp. If -l is not specified, the ls command lists
  78.         only the names.
  79.  
  80.     -c  Use time of creation instead of time of last modification. If
  81.         used with -l, it shows this time. If used with -t, it sorts
  82.         using this time. (Win32 and OS/2 versions only.)
  83.  
  84.     -u  Use time of last access instead of time of last modification.
  85.         If used with -l, it shows this time. If used with -t, it sorts
  86.         using this time. (NTFS and HPFS only.)
  87.  
  88.     -x  The same as -u, for compatibility with previous versions of ls.
  89.  
  90.     -R  Recursively descend subdirectories.
  91.  
  92.     -p  Put a path separator after each name that is a directory.
  93.  
  94.     -C  Force multicolumn output. The ls command tries to list more
  95.         than one filename per line, depending upon the length of the
  96.         longest name and the width of the display screen. Filenames are
  97.         sorted vertically.
  98.  
  99.     -m  The same as -C, for compatibility with previous versions of ls.
  100.  
  101.     -1  Force single (one) column output.
  102.  
  103.     -n  Sort the output by name (default), in alphabetic order.
  104.  
  105.     -t  Sort the output by date and time, from newest to oldest.
  106.  
  107.     -z  Sort the output by filesize, from smallest to largest.
  108.  
  109.     -r  Reverse the order of the sort.
  110.  
  111.     -o  Don't sort: display filenames in the order in which they occur
  112.         in each directory.
  113.  
  114.     -g  List each set of matching files as a group in the order that
  115.         their fspecs are specified. In other words, if '*.h *.c' are
  116.         entered, then the g flag causes all .h files to be displayed
  117.         first and all .c files to be displayed next, etc.
  118.  
  119.         The g flag causes the program to make a separate pass through a
  120.         directory for each fspec, making 'ls' run slower. The default
  121.         behavior is to display all matching files as they are found,
  122.         making only one pass through each directory.
  123.  
  124.     -L  List filenames in lowercase.
  125.  
  126.     -U  List filenames in uppercase. The default is to display DOS FAT
  127.         filesystem names names in lowercase and HPFS filesystem names
  128.         unchanged.
  129.  
  130. You can mix and match the f, s, h, and d flags to include as many
  131. different file types as you wish. If you specify at least one of the s,
  132. h, or d flags, then you must explicitly specify the f flag to include
  133. ordinary files in the listing. If you don't specify one of the f, s, h,
  134. d, or a flags, then the default is fd: list only ordinary files and
  135. directories.
  136.  
  137. You can specify the l (letter el) flag to list file and/or directory
  138. names in "long" format. In this format, each name appears along with its
  139. mode, size, date, and time. The mode (attribute) consists of a set of
  140. characters that are interpreted as follows:
  141.  
  142.         The first character is:
  143.            d   The name is a directory.
  144.            v   The file represents a volume id (DOS only).
  145.            -   The name is a file.
  146.  
  147.         The second character is:
  148.            r   The file is readable (always!).
  149.            -   The file is not readable (never!).
  150.  
  151.         The third character is:
  152.            w   The file is writable.
  153.            -   The file is readonly.
  154.  
  155.         The fourth character is:
  156.            s   The file is a system file.
  157.            -   The file is not a system file.
  158.  
  159.         The fifth character is:
  160.            h   The file is a hidden file.
  161.            -   The file is not a hidden file.
  162.  
  163.         The sixth character is:
  164.            a   The file has been changed (its archive bit is set).
  165.            -   The file's archive bit is not set.
  166.  
  167. ========================================================================
  168. NOTES
  169. ========================================================================
  170.  
  171. An ordinary file is a directory entry whose 'directory', 'system'
  172. 'hidden', and 'volid' attribute (mode) bits are all zero.
  173.  
  174. Filenames are listed on standard output. Filespecs that don't match
  175. any files are listed on standard error.
  176.  
  177. A file specification consists of an optional drive, optional path
  178. information, and a filename. The filename may consist of AIX shell
  179. pattern-matching characters. DOS's filename pattern matching is
  180. simplistic, Win32's and OS/2's is a lot better, but Bourne shell pattern
  181. matching is better still. Also, all versions (DOS, Win32, and OS2) of
  182. the commands in this package support the same level of pattern-matching.
  183.  
  184. A dot within a filename is treated as just another character and not
  185. assumed to be the beginning of a file extension. Indeed, the ls command
  186. has no concept of a file extension. This is compatible with the use of
  187. dots within Win32, NTFS, HPFS, and AIX filenames.
  188.  
  189. Flag characters are case sensitive, just as in AIX. Name comparisons are
  190. case-insensitive, as specified by DOS, Win32, and OS/2.
  191.  
  192. If the -l (long format) flag is listed, each file's modification time
  193. and date are displayed. Specify the c flag along with -l to display each
  194. file's time of creation. Or, specify the u flag along with -l to display
  195. each file's time of last access. Note that the c and u flags don't yield
  196. valid times for a file system (such as DOS or OS/2 FAT) that don't
  197. maintain them. Also note that the DOS version simply shows the time of
  198. last modification for the -lu and -lc flags.
  199.  
  200. You may specify more than one set of flags. For example, you may enter
  201. the commands 'ls -n -l *.c *.h' and 'ls -nl *.c *.h' both list all .c
  202. and .h files in long format, sorted by name.
  203.  
  204. The order in which you specify certain flags is important. For example,
  205. if you specify the -l, -m, and/or -1, the last one entered takes
  206. precedence. Likewise, if you specify -o, -n, -z, and/or -t, the last one
  207. entered overrides the others.
  208.  
  209. If the ls command is displaying filenames in multicolumn format and/or
  210. sorting the names, then ls first stores all of the filenames in memory,
  211. sorts them (n, t, or z flag), and determines how many columns to
  212. display. The DOS version of the ls command may run out of memory for
  213. large file listings. If it does, you should re-run ls with the -1o
  214. (number 1 and letter o) flags: force single-column output and don't
  215. sort.
  216.  
  217. For DOS, filenames are listed by default in lowercase since this is more
  218. readable (especially on smaller displays). For OS/2, HPFS, NFS, and
  219. TVFS, all filenames are displayed as-is. For Win32, all filenames are
  220. displayed as-is. If you want uppercase filenames (such as DOS DIR and
  221. OS/2 GSEE provide), then specify the -U flag. For OS/2 and Win32, the -L
  222. flag will force all names to be shown in lowercase.
  223.  
  224. The Watcom-built versions (Win32, OS/2, and DOS) cannot list the volume
  225. label. The DOS version does not support the -u and -c flags.
  226.  
  227. Enter 'ls -?'  to get help.
  228.  
  229. ========================================================================
  230. EXAMPLES
  231. ========================================================================
  232.  
  233. ls *             These commands all mean the same thing: List all
  234. ls               ordinary files and subdirectories within the current
  235. ls -fd *         directory. They match the same files that the DOS
  236.                  command 'dir *.*' matches.
  237.  
  238. ls *.*           This command lists all ordinary files in the current
  239.                  directory that have an extension (that is, that have a
  240.                  dot in their file name). This is not the same as the
  241.                  'ls *' command nor is it the same as the 'dir *.*'
  242.                  command, since it won't list any files or directories
  243.                  whose name contains no dot.
  244.  
  245. ls -Cn           List all files in the current directory in multi-column
  246.                  format, sorted by name. This is the default behaviour
  247.                  for the ls command when stdout is the display (and when
  248.                  ls is entered with no flags or arguments).
  249.  
  250. ls *.c           List all files in the current directory that end in .c
  251.                  (or have the .c extension, in DOS's words).
  252.  
  253. ls *.c *.h       List all files in the current directory that end in
  254.                  either '.c' or '.h'. Notice that you can enter more
  255.                  than one file specification.
  256.  
  257. ls -a a:         List all files and subdirectories in the current
  258.                  directory of the A: drive.
  259.  
  260. ls -lsh *        This command lists only hidden and system files in the
  261.                  current directory, along with their mode (attributes),
  262.                  sizes, and time and date stamps.
  263.  
  264. ls -d *          This command lists all subdirectories within the
  265.                  current directory. The DOS 'DIR *.' command sort of
  266.                  does the same thing, provided that directory names have
  267.                  no extension and file names always have an extension.
  268.  
  269. ls -l            List each file in the current directory, along with its
  270.                  mode, size, and time and date of last modification.
  271.  
  272. ls -lc           Like -l, except display each file's time and date of
  273.                  creation. (Win32 and OS/2 versions only.)
  274.  
  275. ls -lu           Like -l, except display each file's time and date of
  276.                  last access. (NTFS and HPFS only.)
  277.  
  278. ls -Rd c:\       List all directories and subdirectories on drive C,
  279.                  starting at the root directory. This produces a tree
  280.                  listing of drive C.
  281.  
  282. ls -R c:\[a-m]*.exe
  283.                  List all .exe files on drive C that begin with the
  284.                  letters A through M, inclusive.
  285.  
  286. ls -R c:\my.bat  List all occurances of the my.bat file on drive C.
  287.                  This command performs a "whereis" type of function.
  288.  
  289. ls -R *.c        List all .c files in the current directory and,
  290.                  recursively, in any subdirectories within the current
  291.                  directory.
  292.  
  293. ls -lRdn \       List all directories on the current drive in "long"
  294.                  format, sorted by directory name.
  295.  
  296. ls -lt           List all files in the current directory in "long"
  297.                  format, sorted by date and time of modification.
  298.  
  299. ls -lut          List all files in the current directory in "long"
  300.                  format, sorted by date and time of last access. (OS/2
  301.                  version only.)
  302.  
  303. ls -luo          List all files in the current directory in "long"
  304.                  format, in the order in which they occur in the
  305.                  directory (unsorted). Display the time of last access
  306.                  for each one.
  307.  
  308. ls -lRn          You may specify flags in one or more groups. For
  309. ls -l -Rn        example, these commands all produce identical results.
  310. ls -l -R -n
  311.  
  312. ls -lC1          The same command as 'ls -1'. The m flag disables the l
  313.                  flag, and the 1 flag in turn disables the C flag.
  314.