Black Box 4/BlackBox.cdr/fileutil/stuff2.arj/STUFF.DOC

Text File | 1989-03-20 | 12.7 KB | 332 lines

                                 Stuff  2.0
                                     by
                                 Rahul Dhesi


The executable form of the program Stuff 2.0, as compiled and distributed by
me, is dedicated to the public domain.  Copyrighted source code suitable for
Turbo C 1.0 is also distributed and may be used in conformance with the
copyright statements contained in the source files.

The primary purpose of Stuff 2.0 is to generate pathnames that may be fed to
zoo version 1.5 or later to allow it to recursively archive a directory
hierarchy in compressed form.  Invoke it as "stuff" without any parameters to
get a help screen.  Stuff should work on any MS-DOS system.  IBM
compatibility is not a requirement.

Changes from version Stuff 1.0 are summarized at the end of this document in
the section entitled CHANGES FROM VERSION 1.0.

Stuff is generally used as follows:

     stuff /new | zoo aI newfiles

The above pipeline causes Stuff to generate a list of all files in /new and
its subdirectories and feed them to zoo, which in turn reads each filename
and adds that file to the archive "newfiles.zoo".  Later, the zoo archive
can be extracted with

     zoo x.// newfiles

to recreate the original directory hierarchy.

The general format of a Stuff command is:

     stuff pathnames ... [ conditions ... ]

Following the name of the program "stuff" itself, you need to give a list of
one or more file or directory names in any combination.  Following these you
can optionally specify some conditions that a file must meet before its name
will be listed by Stuff.

In the simplest case, when all you want to do is archive all files in certain
areas, you will simply say:

     stuff /new /old /test | zoo aI backups

The above command will cause all files in the /new, /old, and /test
directories (and all subdirectories, and all subdirectories of
subdirectories, and so on) to be archived into "backups.zoo".  Or you might
archive certain selected files thus:

     stuff *.c *.h /turboc/include | zoo aI cprogs

This archives all *.c and *.h files in the current directory and also
archives all files in /turboc/include and its subdirectories.

For greater control, conditions may be specified.  For example, to archive
only files with certain names, a possible command is:

     stuff / ! -name *.obj ! -name @junk ! -name *.bak | zoo aI sources

This command asks Stuff to search the entire disk beginning with the root
directory / and asks it to list names of all files EXCEPT those that match
the patterns "*.obj" or "*.bak" or any of the patterns inside the file "junk".
The exclamation mark tells Stuff to make the following condition exclude
matching files.

Here is a list of all conditions accepted by Stuff 2.0:

  -name pattern    wildcards ok, * matches all files, dot is not special
  -name @file      read patterns from file, one on each line
  -size N          size is N kilobytes (+N means over N, -N means less than N)
  -mtime N         modified N days ago (+N means over N, -N means less than N)
  -modified        modified since last backup (tests "archive" bit)
  -older filename  older than specified file (false if "filename" not found)
  -newer filename  newer than specified file (true if "filename" not found)
  -limit N         group files together, each group not to exceed N bytes

SELECTING BY NAME

Files are selected by name with the -name condition.  For example:

     -name pattern
     -name @file

Both tell stuff to select a file if its name matches a supplied pattern.  The
second form tells Stuff to get one or patterns, one per line, from the file
whose name is given after the @ character.  See below for more information
about the second form.

In each pattern, the wildcard characters ? and * may be used.  The ? wildcard
matches any one character and * matches zero or more characters.  Arbitrary
combinations may be used, and the dot is not special, so *x* will match
"xyz.doc" as well as "doc.xyz".

To exclude files matching a pattern, use the ! character thus:

     ! -name pattern
     ! -name @file

The first form excludes a file if its name matches the supplied pattern.  The
second form allows you to use the patterns stored in a file.  See below for
more information about the second form.

If a pattern contains no slashes, Stuff attempts to match only the filename
part of each file found.  For example, "/myfiles/sources/stuff.c" will match
the pattern "st*c".  But if the pattern contains any slashes, then it must
match the entire pathname of each file found, so "/myfiles/sources/stuff.c"
would not match "*/new/st*c" but it would match "*sources*/st*c".

If more than one -name condition is specified (without a preceding !), then a
file is selected if it matches any one or more of them.  If a file is
excluded with the "! -name" form, then it is never selected, even if it
matches a pattern.  For example,

     -name *.com -name abc* ! -name /new/*

would select a files called "xyz.com", "abc.exe", and "abc.com", provided
none of these was in the /new directory or any subdirectory in it.  It would
not select a file called /new/abc.com because the ! condition excludes
everything beginning with the characters "/new/".


SELECTING FILES FROM A LONG LIST

The @file syntax allows you to create lists of files to select or exclude.
For example, suppose we have a file called SELECT containing the following
filename patterns, one per line, with no extraneous blanks:

     /bin/*.exe
     /bin/*.com
     *.doc

Now we can use the command

     stuff / -name @select

to print the names of all files that match the patterns /bin/*.exe,
/bin/*.com, and *.doc.  The above is exactly equivalent to typing:

     stuff / -name /bin/*.exe -name /bin/*.com -name *.doc

Due to MS-DOS's command line limit, the use of a file containing patterns
allows you to specify more patterns than can be specified on the command
line.

Patterns and @files may be intermixed on the command line in any order, and
more than one @file can be specified.

The ! operator can be used with the @file syntax.  Exclusion of a filename
like this overrrides all other conditions.  Thus if a filename is excluded
with "! -name pattern" or "! -name @file", then that filename will never be
printed, no matter how many other conditions select it.

If multiple filename patterns are excluded, then all files whose names match
any of the exclusion patterns will be excluded.

Suppose we have a file called STOPLIST that contains the following
patterns:

     *.bak
     *.bat
     *.log
     *.00?

Now if we give the command

     stuff / -name *.* ! -name @stoplist

Stuff 2.0 will select all files that match *.* (i.e. all files that contain a
dot in the filename) EXCEPT those files that match any of the patterns in the
STOPLIST file.

A STOPLIST file is useful if there are some types of files (e.g. backups, log
files, etc.) that you do not normally want to select for archiving. Just put
all the names or patterns in the STOPLIST, and tell Stuff 2.0 to exclude
those.


NOTE:  Stuff 2.0 does a sequential search through all the filename patterns
supplied, whether on the command line or in a file.  Its speed will
significantly slow down if this list is very long.  Keep the list of filename
patterns to be searched to about 30 or fewer.


SELECTING BY SIZE

The condition -size allows selection of files based on if they are equal to,
larger than, or smaller than, a certain number of kilobytes in size.  A
kilobyte is 1024 bytes.  A file is considered to be n kilobytes long if
dividing its size in bytes by 1024 and ignoring the remainder gives a value
of n.  For example, a file that is 10137 bytes long (9.89 kilobytes) is
considered to be 9 kilobytes in size.  To select files that are 8 kilobytes
long, use the condition:

     -size 8

To select files that are more than 8 kilobytes long, use the condition:

     -size +8

Similarly, to select files that are less than 8 kilobytes long use the
condition:

     -size -8

One can use multiple conditions, and all must be met.  Thus

     -size +2 -size -9

will select all files that are 3 to 8 kilobytes long.

As with other conditions, ! reverses the sense of -size, so saying

     ! -size +8

selects files that are not bigger than 8 kilobytes.


SELECTING BY AGE

The -older, -newer, and -mtime conditions allow file selection based on when
a file was last modified.  To select a file that was modified in the last 24
hours, the condition is:

     -mtime -1

which selects files that are less than 1 day old.   As before using !  will
reverse this, so

     ! -mtime -1

selects only files that were not modified in the last 24 hours.  The
conditions -older and -newer allow you to test to see if a file is older or
newer than another file whose name you specify.  For example, the Stuff
command

     stuff / -newer info.txt

searches the entire disk for all files that are newer than the file
"info.txt".  The -older condition is complementary, and again, both may be
combined with ! to reverse their sense, so that

     ! -older info.txt

selects files that are not older than "info.txt" (so they must be of the
same age or newer).  The use of the -newer condition allows you to
intelligently update files in a zoo archive with a command line of this
type:

     stuff /sources ! -name *.obj -newer sources.zoo | zoo aI sources.zoo

This command tells Stuff to find all files in /sources and subdirectories
that are newer than the zoo archive "sources.zoo" (and which are not *.obj
files) and list their names.  Since the datestamp of a zoo archive reflects
the age of the newest file stored in it, the effect of the above is to bring
the zoo archive up-to-date.  Note that a similar (though not necessarily
identical) effect could be obtained with:

     stuff /sources ! -name *.obj | zoo aIun sources.zoo

which tells stuff to list all non-*.obj files, and tells zoo to add only new
or newer files to "sources.zoo".


SELECTING MODIFIED FILES ONLY

MSDOS keeps track of whether or not a file has been backed up.  Some backup
programs will set a file's backup status to be "backed up".  Every time a
file is written to, MSDOS restores its backup status to mean "not backed
up".  Thus it is easy to make sure that only those files that have been
changed since the last backup was done will be backed up this time.  (This
is the idea of an "incremental backup", which involves backing up only
changed files.)

The -modified condition selects a file only if it has been modified since it
was last backed up.  Reversing it with ! selects a file only if it has not
been modified since it was last backed up.

Thus to archive all files that have been modified since their last backup, a
possible command line is:

     stuff / -modified | zoo aI backups

which saves such files into "backups.zoo".  Note, however, that at this
time, neither Stuff nor Zoo resets the file's backup status.


                 MS-DOS BUGS

MS-DOS exhibits much confusion about the use of "/" and "\" to refer to
directories.  Stuff consistently uses the forward slash in all pathnames it
prints, though it will cheerfully accept pathnames typed by the user that
contain backslashes too.  However, in a pattern following a -name condition
or inside an @ file, a forward slash is needed.

Early versions of MS-DOS have a bug that prevents the root directory from
being referred to as ".".  Instead of saying "stuff ." from the root
directory, simply say "stuff /".


GROUPING FILES BY BYTE LIMIT

Stuff 2.0 can be told to print files as groups such that the total size of
files in each group does not exceed a user-specified limit of bytes.  The
syntax to do this is:

     -limit N

where N is a decimal number giving the limit in bytes.  Stuff 2.0 does not
use any special technique to combine files into groups.  It simply remembers
the accumulated byte count and prints a line of dashes (---) as soon as the
total byte count of files seen is about to exceed the limit.  Then it resets
the total and starts counting again.

This feature is experimental at this time, and probably not very useful.


               CHANGES FROM VERSION 1.0

The changes from version 1.0 are the following:

1.   The "-name @file" syntax is supported, allowing a list of patterns to be
placed in a file.  The "-name @file" and "-name pattern" conditions may be
freely intermixed in any order.

2.   If multiple filename patterns are given using "-name pattern" or "-name
@file", a file is selected by Stuff 2.0 if it matches at least one of the
patterns.  Stuff 1.0 selected a file only if it matched all patterns given.

                                      -- Rahul Dhesi 1989/03/19