PDP-10.its/doc/_info_/find.info

FIND					(3/14/76) PDL
					(6/13/76) PDL
			Last update:	(7/6/76)  MRC


A new version of FIND has been written.  It has several nice
features and seems somewhat faster than the old one.

---------------
Commands:

:FIND <output-file> _ <directories> <devices> <files> <switches>

<directories>
   You may specify any number of directories to search.  This defaults
to the whole disk (i.e., all the directories in the MFD.
   You may give directories in * format a la DIRED:  LIB***; would
specify all directories whose names start with "LIB".
   If a NIL directory specification is given, as in :FIND ;, this implies
to search the MSNAME; directory.

<devices>
   You may specify any combination of DSK-like devices.  This includes
DSK, COM, TPL, SYS, and AR*.  If not given explicitly defaults to DSK.
Giving *: means "the DSK and all ARC-style devices".  Giving AR*:
means "all ARC-style devices".  You may also give archives explicitly:
ARC:AR1:, and so on.  SYS: maps into the SYS; and SYS1;
directories, COM: into COMMON; and so on.

Referencing other ITS sites via find has been temporarily removed until
a less anti-social way of implementing it has been found.

Funny devices:  FIND will search for any device that you tell it is
"like" either a disk or an archive.  For example, an archive you have
renamed to be the file ZORK > can be searched by using a special switch,
the ARC or ARCHIVE switch:  /ARC ZORK: says to look for the ZORK device
which is accessed like the ARC device (that is, has a directory like the
ARC device and is called ZORK > on some directory).  Additionally, you 
may specify DSK-like (but unknown) devices by /DSK <device>:, which assumes
the UFD of the device is available by OPENing .FILE. (DIR) on that device.
NOTE:  "Funny" DSK-like devices cannot be searched on remote ITS hosts!!!

<files>
   You may give any number of DIRED-style file specs.  If you give only
one name (as in :FIND TS) the second defaults to *.  If you want to give
several single names, separate them by ,;  :FIND FOO,BAR,BLECH,TS.

<output-file>
   A file specification followed by an _ as the first thing input
causes output to be put into that file.  Default of course, is to go
to TTY:.  If you give an output file, the default is <MSNAME>;FIND
OUTPUT.

(Note:  If your file search specification has _'s in it, and they
could be confused with an output specification, quote them using
^Q.  For example:

:FIND PDL;_MSGS_  is ambiguous.  Do you mean output to PDL; all files
		  which match MSGS_ or do you mean all files on PDL;
		  which match _MSGS_?  Quote the _'s in the latter
		  case.  However,

:FIND _MSGS_	  is not ambiguous, because nothing precedes the first
		  _, meaning it can't be the signal for an output file.

What actually happens is that the first unquoted _ is examined when
read, and if there is something that looks like it might be a file
specification to the left of it, that file spec is used as the output
file.

<switches>
   Any number of switch names, each prefixed by a / or a &.  Legal
switches are in the following list:

TOTAL  (or SUMMARY, TOTALS, SUM)
     Print total files, blocks, and links at end of run.

OR  (or FIND or ELSE)
     This switch delimits search specifications.  It is described in
detail below.

TO <file-spec>
     List files which are links to the file-spec given (the spec may
contain *'s and so on).

LINKS (or L or LINK)
     List files which are links.

AUTHOR <uname>
     List files created by the author specified.  To specify "any non-
directory author" give authorname "?".

DUMPED
     List files that have been dumped.  By convention, LINKs are not
dumped, and therefore it is often useful to couple this switch with
&NOT LINK as well.

REAP (or SAFE or PROTECTED)
     List files whose "Do not REAP" bits are turned on.  These
are indicated in the normal "LISTF" line by having a $ (mnemonic
for expensive) next to the dump bit character.

OPEN (or WRITE)
     List files open for writing.  This is useful mostly to find
losing files in Archives, unless you are just nosy.

DELETED
     List files to be deleted when closed or deleted from unmounted
pack.

PACK <number>  (or PCK or DRIVE)
     List files on a particular disk pack.

ALLOC
     List files on allocated packs.

ARC <device>:  (or ARCHIVE)
     See above, under <device>.

DSK <device>:  (or DISK)
     See above, under <device>.

NOLF  (or NOLIST)
     Don't print the LISTF lines for matches, only print the summary
at the end.  Primarily useful along with /TOTAL.

WORDS  (or W or WORD)
     Print total words in file in LISTF lines, not BLKS+WDS.

FLOATS  (or F or FLOAT)
     Print floating point size of file:  BLKS.<words*100./1024>.

     Several switches take as their argument a "range".

SIZE <range>  (or SIZEB)
     List files which are within the range of the number of blocks
specified.

SIZEW <range>
     Like SIZE, only specifies file sizes in words, rather than blocks.

EXTRA <range>
     Files with the indicated number of unused words in the last block.
For example, /EXTRA > 1000 would be files whose last blocks are almost
empty.  This is useful for finding candidates for archiving.

DATE <range>  (or CDATE)
     List files created within the range of date specified.  Dates are
specified in one of several ways:
     (a) as though they were large fixes, i.e.; January 1 is 760101
and December 31 is 761231.
     (b) as up to three numbers separated by slashes, i.e.; 1/30/76.
If specified in this mode the year is expected to be last.
     (c) as (b) but separated by dots, i.e.; 76.1.30.  In this format
the year is expected to be first.
     The default date when a date is asked for is today.  It may be
given directly (:FIND /CDATE TODAY, for example) or used as a base
date.  For example, :FIND /CDATE 2/20 implies February 20 of the
current year, and :FIND /CDATE 10 implies the 10th of the current
month.
     A date specification may be combined with a time specification:
"/CDATE SINCE 5/1 13:00" means implies May 1 at 1pm.

RDATE <range>  (or REF)
     List files whose reference date is within the range given.

TIME <range>   (or CTIME or T)
     List files whose creation time is within the range given.  Times
are specified in standard form on a 24 hour clock:  20:30 for 8:30 pm,
for example.  Note that a TIME spec does not combine with a date spec:
"/DATE 5/1 /TIME 13:00" is different in meaning from "/DATE 5/1 13:00".
The former implies "Created on May 1 or created on any day after 1pm."

     To specify a range, give one of the following:

GT <number>	(or >,GREATER)
     Means "match any number greater than my argument".

LT <number>	(or <,LESSER)
     Means "match any number less than my argument".

EQ <number>	(or =,EQUAL)
     Means "match any number equal to my argument".

BTW <num1> <num2>	(or BETWEEN)
     Means "match any number within the range specified by my arguments.

     If no range indicator is given but a number is, the marker "EQ" is
understood.

     As a convenience, "BEFORE" "SINCE" and "ON" work as well, since
they are mnemonic with dates.  Additionally, the switches with these
names map into "CDATE <switch>".
     When the range is a range of dates, "TODAY" is understood to have
its obvious meaning.  Also "TODAY" as a switch is understood to mean
"CDATE TODAY".

     Examples:

:FIND PDL; &SIZE > 10		; find all files more than 10 blocks.

:FIND PDL; &BEFORE 760000	; find files created '75 and earlier.

:FIND PDL; &REF BETWEEN 760120 760000
				; find files referenced between Dec.
				; 31 and Jan 20.

:FIND PDL; /CDATE BETWEEN 5/4 5/5 10:30
				; find files created on May 4 or on
				; May 5 before 10:30 am.

   Switches may be specified in either AND form (&), or OR form (/).
Additionally the complements (NAND and NOR) of switches are available
by typing /NOT <switch> or &NOT <switch>.

   For example, use the AND form to restrict the search:

:FIND TS DDT &LINK		will find only links called TS DDT.

whereas

:FIND TS DDT /LINK		will find all links and all TS DDTs.

and finally

:FIND TS DDT &NOT LINK		will find all non-link TS DDTs.

   Note that

:FIND TS DDT /NOT LINK

will find all TS DDTs AND! all non-links.  Moral:  Be careful with
your /'s and &'s.

=================
Multiple Search Specifications

	There is a special switch, called either OR, ELSE, or FIND,
whichever you prefer, for delimiting search specifications.  For example
saying:

:FIND TS DDT &LINK TS FIND &NOT DUMPED

gives an infulfillable search path, a file simultaneously named "TS DDT"
and "TS FIND".  You could do two separate FINDs, but that is untasteful.

Using the OR switch:

:FIND TS DDT &LINK /OR TS FIND &NOT DUMPED

causes two search specifications to be created:  Links named "TS DDT"
and files named "TS FIND" which are also not dumped.

-----------------
Details of Command Input:

If you terminate a command line with +, you will be asked to give more
commands.  Ditto if you give an empty JCL line.

To quote special characters (like _ ; :), put a ^Q in front of them.
This will turn them into normal symbol constituents.

Typing ^S or ^G at any time during the running of FIND will cause it
to kill itself.

-----------------
Examples:

:FIND SYS;		-- like LISTF SYS;

:FIND SYS;SYS1;		-- two LISTFs in a row

:FIND *:PDL;		-- list all the files on PDL's disk and in his
			   archives.

:FIND AR9:		-- listf everyone's AR9.

:FIND AR9		-- give the names of all the AR9s in the world

:FIND AR*:MAZE		-- find all the MAZEs in archives

:FIND *MUD**;FOO,BAR	-- find all the FOOs and BARs on 0MUD51, 1MUD51
			   and so on.

:FIND TPL:_PDL;TS *	-- find all TS files on PDL;, printing list on
			   TPL:

:FIND /TO SYS;TS NNDDT	-- find all files which are links to SYS;TS NNDDT.

------------------
Details of Search Specifications:

	When you give a command to FIND, you are really delimiting FOUR
separate searches:

0) A list of ITS's to get M.F.D.s from.
1) A list of directories to search.
2) A list of devices to search.
3) A list of tests to apply to each file in each directory searched.

	Zeroth, the ITS whose M.F.D to read is selected.  The local
ITS (DSK:) is always done first if it is one of the ITS's asked for.

	First, the MFD is read in and the list of directories matching
the directory specifications given is kept.  All other directories are
ignored.  This number of directories may be as few as one or as many as
the whole MFD.

	Secondly, the directories of the devices in the second list are
read in one by one.  The default in this case is the DSK: device, but of
course may include ARC devices as well.

	Thirdly, the tests specified are applied to each file in each
directory.  The files which match any search spec have their directory
lines printed out.  Once a file matches a search spec it is no longer
tested with subsequent specs.

	Note that currently (forever, perhaps) the file search specifications
given are done in all directories.  There is no way to do a given search
in only a few of the specified directories.  This may change someday.

------------------
Notes:

 1) So far, there is no DFIND for this version of FIND.
 2) Reading of ARC-style directories is not done via the ARC device it-
    self, so it is very fast and causes very little overhead.