     SLS(1)                                                               SLS(1)
                                    7 March 1989

     NAME
          sls - list information about file(s) and directories

     SYNOPSIS
          sls [ -adlpsuLR ] filename ...

     DESCRIPTION
          Sls is a program designed to overcome the limitations of the standard
          UNIX ls(1) program, providing a more consistent interface to file
          inode information.  It is particularly designed for use by shell
          scripts to make obtaining information about files easier.  It uses
          printf(3)-style format strings to control the sorting and output of
          file information.  Advantages of sls over ls:

          o  Allows complete specification of the output contents - field
             (column) order, field widths, right/left justification, and zero-
             fill.

          o  Allows complete specification of the sort order independently of
             the output options - output can be sorted on one or more fields.

          o  Has consistent, user-definable file date formats - ls's are
             inconsistent and hard to parse (the seconds are never displayed,
             the year is shown instead of the time for files more than 6 months
             old, etc.).

          o  Has ``normalized'' output (no summary lines or changing formats).

          o  Allows specification of delimiter char(s) - the characters between
             fields - which makes the output easier to parse in shell scripts.

          o  Won't stat files if it's not necessary (e.g., ``sls <dir>''); in
             the trivial (but common) case of calling sls on a directory (or
             list of directories) with no options, it will simply read the
             directory file and display the file names, sorted alphabetically.
             For very large directories, this is much faster than ls, and gets
             around command line limitations of the various login shells when
             using echo(1).

     OPTIONS
          -a   List all entries; in the absence of this option, entries whose
               names begin with a `.' are not listed.

          -d   If argument is a directory, list only its name (not its
               contents).

          -p outputstr
               Set the list of output fields according to the printf-style
               outputstr (see "SORT AND OUTPUT OPTIONS", below).

                                        - 1 -      Formatted:  November 19, 1999

     SLS(1)                                                               SLS(1)
                                    7 March 1989

          -l   Perform long-form output according to default format ( ls-style)
               or environment variable SLS_LONGFMT, if set.  This effectively
               sets the -p option string to a predefined value, providing a
               convenient shorthand for a detailed listing.

          -s sortstr
               Sets the sort order according to the printf-style sortstr (see
               "SORT AND OUTPUT OPTIONS", below).

          -u   Sets the default display format for file dates to be the same as
               ls (``Mmm dd HH:MM'' for newer files, ``Mmm dd yyyy'' for older
               files).

          -L   If argument is a symbolic link, list the file or directory the
               link references rather than the link itself.

          -R   Recursively list subdirectories encountered.

     SORT AND OUTPUT OPTIONS
          The option strings supplied with the -s and -p options determine the
          sort order and output format of the listing.  The option string is a
          single argument consisting of two types of objects: plain characters,
          which are simply copied to the output stream, and conversion
          specifications, each of which causes a particular member (or field) of
          the stat(2) structure to be sorted or printed.  (The correspondence is
          not quite one-to-one, but it's close.)  Plain characters and field
          widths in the sort option string are ignored.  Each conversion
          specification is introduced by the character % (unless two appear
          together, in which case a single one is output).  After the %, any of
          the following may appear in sequence:

               An optional `-' flag: for the -p option, it specifies left-
               adjustment for string-type fields (no effect on numeric fields);
               for the -s option, it means reverse the sort order on this field.

               An optional decimal digit string specifying a minimum field width
               (-p option only).  If the converted value has fewer characters
               than the field width, it will be padded on the left (or right, if
               the left-adjustment flag has been given) to the field width.  If
               the converted value has more characters than the field width, the
               field width will be ignored.  If the digit string has a leading
               ``0'', numeric-type fields will be zero-filled on the left to the
               width of the field.

               A (required) flag character, which results in the conversion of a
               field from the stat structure for each file.  Some flag
               characters may be followed by optional modifier character(s).
               Each flag character has a default field width and format.  The
               flag characters and their meanings are:

                                        - 2 -      Formatted:  November 19, 1999

     SLS(1)                                                               SLS(1)
                                    7 March 1989

               a    last access date.  This can be followed by a quoted date
                    format string (see "DATE FORMAT STRINGS", below).  If no
                    date format string is supplied, the default format shows the
                    time and year; this can be overridden by setting the
                    SLS_DATEFMT environment variable to a suitable date format
                    string.
               b    number of allocated (512-byte) blocks; optionally followed
                    by one of mkc to specify output in megabytes, kilobytes, or
                    characters (the default).
               c    inode change date.  This can be followed by a quoted date
                    format string (see "DATE FORMAT STRINGS", below).  If no
                    date format string is supplied, the default format shows the
                    time and year; this can be overridden by setting the
                    SLS_DATEFMT environment variable to a suitable date format
                    string.
               d    device number the inode resides on.
               g    ascii group name of the owner of the file.
               G    numeric group number of the owner of the file.
               i    inode number of the file.
               k    optimal file system block size.
               l    number of hard links.
               m    last modify date.  This can be followed by a quoted date
                    format string (see "DATE FORMAT STRINGS", below).  If no
                    date format string is supplied, the default format shows the
                    time and year; this can be overridden by setting the
                    SLS_DATEFMT environment variable to a suitable date format
                    string.
               n    file name; optionally followed by one or more of abs: a to
                    specify ascii output of non-printing chars; b to specify
                    basename only (i.e., file name w/o leading directory path,
                    if any); and s to specify a filetype suffix - this marks
                    directories with a trailing slash (/), executable files with
                    a trailing asterisk (*), symbolic links with a trailing at-
                    sign (@), and AF_UNIX domain sockets with a trailing equals
                    sign (=).
               N    file name, with symbolic links' linked-to file name shown as
                    ``-> name''.
               p    ascii permissions (same as in ls).
               P    octal permissions.
               r    device number that the file resides on.
               s    file size; optionally followed by one of mkc to specify
                    output in megabytes, kilobytes, or characters (the default).
               t    file type (same as in ls).
               u    ascii user name of the owner of the file.
               U    numeric user id of the owner of the file.

     DATE FORMAT STRINGS
          The a, c, and m flag characters use a default format of Mmm dd yyyy
          HH:MM (``%h %d 19%y %H:%M'').  This can be changed by setting the
          SLS_DATEFMT environment variable to a suitable date format string; by
          specifying the -u command line option, which requests ls-style dates;

                                        - 3 -      Formatted:  November 19, 1999

     SLS(1)                                                               SLS(1)
                                    7 March 1989

          or by following the flag character with a quoted format string of the
          type used by date(1) (with several extensions; see below).  (Note that
          either single or double quotes must delimit the date format string in
          the -p option string, so use your shell's particular syntax for
          embedded quotes.) The date format string may contain plain characters,
          which are copied to the output, or any of the following format
          modifier characters (preceded by a `%'):
               %    print a percent sign.
               a    print abbreviated weekday (Sun to Sat).
               d    print day of month (01 to 31).
               h    print abbreviated month (Jan to Dec).
               j    print julian date (001 to 366).
               m    print month of year (01 to 12).
               n    print a newline.
               r    print time in AM/PM notation (``HH:MM:SS ?M'').
               t    print a tab.
               w    print day of week (0 to 6) (0=Sunday).
               x    print date in system format (number of seconds since the
                    epoch).
               y    print last 2 digits of year (00 to 99).
               D    print date as mm/dd/yy.
               E    print day of month with no padding for single-digit dates.
               F    print full month (January to December).
               H    print hour (00 to 23).
               M    print minute (00 to 59).
               S    print second (00 to 59).
               T    print time as HH:MM:SS.
               W    print full weekday (Sunday to Saturday).
               X    print date in system format, using the number of days only
                    (divides seconds by 86,400).

     EXAMPLES
          To produce the same output as ``ls -l'':

          sls -u -p '%t%p %2l %-u %s %m %N' To list the size (in kbytes), access
          and modify dates (no times), and file names (no pathname), sorted by
          size (largest first):

          sls -s %-s -p '%sk  %a"%h %d 19%y"  %m"%h %d 19%y"  %nb' /usr/mydir
          How a shell script might get the last-modify date on a file with sls
          vs.  ls (assume that SLS_DATEFMT="%h %d %H:%M"; remember that you have
          no control over the time vs. year field with ls):

          FILEDATE=`ls -l file | awk '{print $5,$6,$7}'`
          FILEDATE=`sls -p %m file`

     FILES
          /etc/passwd    to get user names for %u output format flag.
          /etc/group     to get group names for %g output format flag.

                                        - 4 -      Formatted:  November 19, 1999

     SLS(1)                                                               SLS(1)
                                    7 March 1989

     BUGS
          It is impossible to distinguish between two files with the same name
          in two different directories with the %nb output format flag.  There
          are several features of the ``standardized output'' nature of sls that
          are incompatible with ls, and may cause some initial confusion; these
          are mentioned below.  The default alignment for string-valued fields
          (right-justified) does not match ls, but is consistent with the C
          library function printf (which uses the ``-'' option flag to specify
          left-justification).  sls does not automatically eliminate the
          directory part of the file name in the listing when supplied with a
          single directory name argument; the user must explicitly request that
          with the %nb output format flag.  The symbolic link notation
          ``linkname -> name'' that ls automatically provides with -l output
          must also be explicitly requested by the user with the %N output
          format flag.  Sls has no multi-column output capability.  The default
          format for dates in sls displays both the time and year, resulting in
          wider output (see ``DATE FORMAT STRINGS'' section for information on
          overriding this default).

                                        - 5 -      Formatted:  November 19, 1999