Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 487.lha / whereis / whereis.doc < prev next >

Wrap

Text File | 1991-03-11 | 27.5 KB | 613 lines

--- whereis.doc --- Monday 07/01/91 ************************************************************************** * whereis.doc (english) for whereis V1.21 (07-Jan-91) AMIGA-VERSION by * * Roland Bless. All rights reserved. Doc lines: 612 * * (C) 1989/90 by Byteable Software Products (Roland Bless) * ************************************************************************** Yaffu? Yet another "find-that-file" utility? Nah, look at the features of "whereis"! ;-) Please read this documentation to inform yourself about: 1) What is "whereis" (good for)? 2) How is it used? 3) How it works. 4) What the error-messages mean. Copyright/Distribution: ======================= The program is PUBLIC DOMAIN (what else for this shabby stuff?) and should be spread to any AMIGA-user around the world, because it is a utility that saves time (esp. if you're using a harddisk, as I do!). Please distribute or copy it ALWAYS with this documentation! There are only two restrictions of distribution: *************************************************************************** * This software may be distributed for non-profit only!! * * No redistribution of a changed source and/or executable without the * * permission of the author!!! Please ask me first. See address below.THANX* *************************************************************************** About this documentation: ========================= In some examples the quotation marks "" and '' must/need not to be typed. They are only used to emphasize what you have to type in. Asterisks are sometimes used to *emphasize* words. Although there is a short info about the switches of "whereis", please read this doc in its entirety to get the maximum benefit of this program. If you're reading this in an editor or text-display program, you can jump to the sections with searching for 1), 2), 3), or 4). RELEASE HISTORY at the end of this document!! German manual also available! Overview of functions: ====================== Format: whereis [-acdfijnpst] [dev:path] filepattern Wildcards * and ? in the filepattern (strictly;-) allowed! You can abort anytime with CTRL-D or CTRL-C. Switches: -a all. Same as -st, so date and size will be displayed. -c CASE-SENSITIVE-Search -d dirs only! Only directories are displayed. -f files only! Files are displayed only, no directories! -i Version-Info -j jump into dir! Interactive "cd" function. If wanted, a "cd" will be executed and the search aborts. Your current dir has changed. -n no subdirectories! Subdirectories are not scanned. (Doesn't make much sense, except for listing functions (e.g. 'whereis -nfa "" *')) -p Detailed pathnames! Displays detailed pathnames, if a path was given as an argument. -s sizes please! Displays sizes of the found files. -t time & date! Displays date and time of last change of a file. Format: dd-mm-yy hh:mm:ss (Day-Month-Year Hour:Minute:Second) 1) What is "whereis" (good for)? ============================= "Whereis" is a utility which searches a file(name) on (hard)disk and shows you the path to this file. Because AMIGA's power is only revealed if you've installed a hard-disk (and AMIGA's commands are often loaded from disk (c:-dir)), some hard-disk users (like me) will loose overview about the stored files. If you have hundreds or thousands of subdirectories and don't know in which of them the program "DiskSalv" was, just type in: "whereis disksalv" and "whereis" will search through your whole active volume. You don't have to look for with "list" or "dir" manually. All files matching the given filename (-pattern) are displayed. "Whereis" combines a "find that file"-function with certain list functions: you can use it as "fnams/recurdir/mydir"[1] (or whatever that little programs are called) to collect the filenames and give them to "ZOO" which then can compress whole subdirectories or volumes. "Whereis" will do that job savely for you! ** Note: "whereis" can only be started from a CLI or SHELL (sorry WB Users!). [1] "RecurDir" or "mydir" (that's how the author (Stephen Vermeulen) named it) was released on Fish-Disk 284. It is recursive programmed and 5516 Bytes long. Features of "whereis": ====================== + Case dependent/independent (switch -c). + Wildcards * and ? possible. + Abortable at any time (with CTRL-D or CTRL-C). + Interactive mode which allows to change your current dir. + Non recursive algorithm -> no problems with stack-sizes (not like LookFor or RecurDir) + Works also as "fnams"/"RecurDir". Use "whereis" with pipes. (archives all filenames from subdirectories for "ZOO", look below) + Can search on any file-oriented AmigaDOS-device and in any sub-dirs. Can be used as a "list all". + Displays date and size of files if wanted. + some other useful options. 2) How to use "whereis": ===================== If the program was not renamed, you can start it from CLI with: whereis [-acdfijnpst] [dev:path] filename The arguments in braces are optional that means they need not to be entered. If "whereis" is called without any argument, it will display a hint for usage. It doesn't matter where the options/switches are placed. All options/switches are preceeded by a '-'-sign. Another possibility to let "whereis" run, is to let it run in the background by "run", "Arun" or "runback" and so on...(to abort it, when running in background, just send via the "break" command the break-signal, e.g. "break 2 all"). To redirect the input/output is also allowed, but please note the '-j' switch, which will always need an interactive input! If the input isn't interactive, "whereis" will abort with "ERROR: Input must be interactive!". And now something about the syntax: ----------------------------------- If you enter "whereis filename", the searching for "filename" starts from the root directory of your current active device/volume/partition. This "filename" can contain the so called "wildcards" * and ? (therefore better "filepattern" than "filename"). - wildcards: "*" stands for none, one or more character(s). ---------- (identical with #? in AMIGA-DOS) "?" stands for just one character. You can use multiple *s and ?s together!! Examples: *.info stands for all files containing .info at the end of their name. *disk* stands for all files containing "disk" anywhere in their name. ?a* stands for all files containing an "a" as second character in their name. ...and so on... Please note a special behaviour: Is there one or more ? at the *end* of the pattern, it is possible that ? stands for *none* character, too! For example: "a????" displays all files with an "a" as first character and 5 characters AT MOST, but all files with less than 5 characters in their name are displayed, too (so even 'a', 'ab','abc'...etc.)! - pathnames: ---------- In addition to the necessary filename-pattern you can command "whereis" in which directory it should look for. E.g. df0:,dh1:,usr:bin,/bin,include and so on... It doesn't matter in which sequence filepattern and pathname occur, because "whereis" is a little bit "intelligent"! To separate the filepattern from the pathname there must be a ":" or a "/" in the path. Otherwise "whereis" will always identify the first argument as pathname and the second as filepattern! It is allowed to use "" for the current directory and / for the parent directory or : for the root-dir of the current active volume. You must enter the path separated from the filenamepattern, because it would not make much sense to join them. Consider the following example: "whereis dh1:test" This looks like test were located in the root-dir of dh1:, but "test" is possibly found in "dh1:usr/bin/"? If you recognize this conflict, please don't be annoyed about this little extra space. If you nevertheless join the path and searchpattern "whereis" will reply with: "ERROR: Please no path in the filename/pattern! See usage!". Examples: "whereis usr:bin test" will search from "usr:bin" down through all sub-dirs for "test" and is equivalent to "whereis test usr:bin" "whereis bin/ test" will search in the directory "bin" (and downwards) for test, if "bin" is a sub-directory of the current active directory. Equivalent with "whereis test bin/" and "whereis bin test" . *Not* equivalent would be "whereis test bin" (will search for bin!). "whereis df1: readme" searches for readme on df1:. 'whereis "" test' searches downwards from the current active directory 'whereis / test' searches downwards from the parent directory 'whereis : test' searches downwards from the root-directory "whereis /// test" is also allowed! - options/switches: ----------------- switches are always preceeded by a '-'. a: All. -a is equivalent to -st. -a causes the output of size and date/time of the found files. c: CASE-DEPENDENT or CASE-SENSITIVE. -c instructs "whereis" to distinguish upper case from lower case letters. The default value is not to distinguish. d: Directories only! Only names of directories will be displayed. f: Files only! The outprinted names are exclusively file- and *not* directory-names. This option excludes '-d' and vice versa. If you use '-df', the output will be none! (Doesn't make much sense, right?) i: info. Prints the actual version-number of your version. j: jump into dir! This is an interactive useful option: If "whereis" finds a matching filename it will prompt "Change to that dir? [yNq]:". Now you have three possible responses: y,Y: Yes, change the current directory of your cli or shell into that in which "whereis" found that filename. If "whereis" displayed a dir- name, it would change to that dir. q,Q: Quit. Cancels the search ("whereis-- Aborted!") and you're back to your current dir which was active before you started "whereis". n,N: No, don't change the current dir (skip). Continues the search...! All other Keys behave like n,N (therefore N is capitalized in [yNq]) and continue the search. Please note that this option is only active with an interactive standard- input-device (You must be able to enter something!), otherwise "whereis" will abort with an error message: "ERROR: Input must be interactive!", or you'll just get the message "Change to that dir? [yNq]:", because the standard-input was redirected. In this case, the best is, to cancel with q or Q and start again without stdin redirected! Not allowed are e.g.: "run whereis -j test" or "whereis <nil: -j test" This option automatically activates '-p' (detailed pathnames). n: No sub-directories! Only the named directory is scanned and not the nested sub-directories. If no directory/pathname was given, only the root-dir will be scanned. This option may seem to contradict with the sense of "whereis", because you seem already to know, where the file(s) is/are located. I just considered the list-function of "whereis" and found out that in some rare cases this may be helpful (think about "whereis : * -dn"; it will list all branching directories from your root-dir). p: Detailed pathnames! Without any pathname as argument (e.g. whereis test) '-p' hasn't got any effect, because "whereis" always displays the most detailed path, likewise if the option '-j' is active (AmigaDOS does the same: if you enter "cd usr:work", the "cd" will show the detailed path (e.g. MyHD1:usr/work) and not "usr:work"!) With a given pathname (e.g. whereis dh0:usr test) "whereis" (*without* the option '-p' activated) displays the *short* path that means the path from the given pathname to the found file and not the whole path from the root directory to this file. This takes advantage of "assigned directories": For example "etc:" is an assigned directory and is located in "Rob-HD1:usr/etc". Supposing the file "test" is located in etc:, then '-p' has got the following effect: Input: Output: "whereis etc: test" --> "etc:test" "whereis -p etc: test" --> "Rob-HD1:usr/etc/test" Supposing usr: is your current active directory, then you'll get this: 'whereis "" test' --> "etc/test" 'whereis -p "" test' --> "Rob-HD1:usr/etc/test" If you activate the "LONGPATH"-option, the detailed path will be shown, that means also "Rob-HD1:" instead of "dh1:". s: Sizes (please)! The size of the found files is displayed. If "whereis" displays a directory, "(dir)" is printed instead of a size value. This option is helpful, if you have some versions of one program on your hard-disk and you want to know, which versions are being displayed (consider that new versions must not always be longer!). In this case use: t: Time and date (please)! Date and time of the last change of the found file are displayed. This is also useful to distinguish different versions of a file (see also option '-a'). The format of the date is: dd-mm-yy hh:mm:ss (day-month-year hours:minutes:seconds) --- It is not (like in UNIX) of importance where you set the options: whereis -c dh0: test whereis dh0: -c test whereis dh0: test -c are all equivalent. It doesn't matter either, whether the options stand alone or are encounted behind one '-': whereis -cfp usr: test whereis -p usr: test -c -f whereis -f usr: -p test -c whereis -c -p -f usr: test whereis test -pfc usr: These calls are equivalent, too. - "whereis" and PIPES: Forget "fnams"/"recurdir"! ----------------------------------------------- The archive-program "ZOO" isn't able yet, to pack whole directories with their sub-dirs (or whole volumes). Instead it has got an option I, which lets "ZOO" read all filenames to compress from standard-input. To collect these filenames, there were written some utilities (I got "fnams" and "recurdir" [1]) Both programs have got one great disadvantage: they work recursive! That causes sometimes trouble with your STACK-size and then the GURU will visit you. I prefer programs, which can run with a default stack-size of 4000 bytes. Because for each program you need to change your STACK-size, maybe you'll get confused (think of each process started from the shell with a huge stack-size: this will eat up your memory! With 3MB I got enough, but I find it nasty to waste memory!). So "whereis" allocates memory, instead of requiring large stack-sizes, and naturally warns you and aborts correctly, if you run out of memory. Recurdir just said goodbye after scanning 8 nested dirs (If you're running UUCP-software, you'll soon get this depth) with a stack of 4000 bytes. Note that recurdir/mydir is already 5516 Bytes large and recursive. If you enter "whereis >usrdir -f usr: *", you can find the whole directory-tree of usr: in the file "usrdir". Ideal is the usage of "whereis" with pipes: ------------------------------------------- Example for the ARP-Shell: whereis -fp usr: * | zoo aI usrfiles Normal Shell: run whereis >pipe:files -fp usr: * + run zoo <pipe:files aI usrfiles This should run without any problems [2]! You can get a sorted output in the ARP-Shell with: whereis dh1: c* | sort Because of this possibility I didn't implement a sort option... [2]: Attention! The PIP: device from ARP 1.3 (it's the ConHandler from ConMan) can guru! The bug is obviously caused by the ConHandler.library V34.6, because other programs also lock up, but run fine with the PIPE: device: e.g. type foo | sort (If foo is large enough, sometimes the PIP: will lock up) Because of safety you should perhaps prefer the PIPE:-device. 3) How "whereis works: =================== "Whereis" scans all sub-directories branching from the named and displays files, which match with the search-pattern on standard-output (STDOUT). "whereis" is not programmed recursive and should not cause a stack overflow! If an error occurs at execution, "whereis" will display an error-message on the standard-error-output (STDERR). If you redirected STDOUT, the error-message will appear on your CLI-Window and not in your output-file. If you made a mistake and don't want to waste time, you can always abort the scanning with: CTRL-d or CTRL-c The message "*** BREAK ***" will follow. BUT: The break-signal (CTRL-c/d) is only detected, if "whereis" climbs up one directory. That means, if you let *display* "whereis" a lot of files (e.g. "whereis c: *"), it may take a while to react and abort, but "whereis" will ABORT ALWAYS! One CTRL-D is enough [3]! If there is not a lot of output, CTRL-c will break as good as CTRL-D, but during output to the window it may react worse than CTRL-D (try "whereis *"). Just a slight delay will be recognized during normal use (not as a "list" command abused), and therefore no problems should arouse. I decided in favour of sparing run-time to handle the break signal not after each scanned entry, therefore you must accept this litte delay and disadvantage. No advantage without a disadvantage... The memory is freed decently at any abort caused by breaks or errors or the '-j' interactive mode. Everytime "whereis" aborts with the message "-- Aborted!". Everytime "-- Aborted!" appears, "whereis" returns an error code (RETURN_ERROR=10). Sometimes other codes are returned. [3]: A WARNING to all ConMan-Users (V1.3): Seems only to concern conhandler.library V34.6: If you press CTRL-c or CTRL-d to long, the machine will crash! That's no bug of "whereis", but of ConMan V1.3. It took some time for me to recognize that my setsignal-routines are ok. Using NEWCON: or (the original) CON: you'll have no problems! - How to use "whereis" more efficiently ------------------------------------- Reduce, if possible, the directories that should be scanned! Use "assigned directories": e.g. "whereis utils: disksalv" The scan-time will be shortened, because to search a whole partition or hard-disk will take a while (ca. 1 min for 20MBytes, depends strongly on your "scan- speed"/"access-time" of your hard-drive!). Another possibility is, to start "whereis" as a background-process, while you are working on other tasks (what the hell is Multitasking else for?): e.g. "run whereis >T:found dh1: *.c". Perhaps that is to use, if you can't restrict the search to a few directories and must search the whole volume, but you want to continue your work (write a text or program etc...). 4) What the error-messages mean: ============================= Possible error-messages and their causes: "FATAL ERROR: Not enough memory available!" ------------------------------------------- Cause: Perhaps other programs allocated too much memory. "Whereis" needs just a few bytes of memory to remember the directories, which type of memory, FAST-, CHIP- or what else RAM, serves doesn't matter. "ERROR: Can't find that directory or device:" --------------------------------------------- Cause: Perhaps you mis-spelled the path. "Whereis" cannot get a "lock" on this directory or device! "ERROR: Destroyed entry! Couldn't examine this ' '. Very strange!" ------------------------------------------------------------------ Cause: I don't know either!...strange: "whereis" was able to get a "lock" on the entry, but EXAMINE returned an error! "ERROR: Can't handle so many arguments. See usage!" --------------------------------------------------- Cause: You gave "whereis" more arguments than just the pattern and the path. "ERROR: Please no path in the filename/pattern! See usage!" ----------------------------------------------------------- Cause: You joined path and pattern! The filename contains a "/" or ":". See section "How to use whereis - pathnames". "ERROR: Illegal Option ' '!" ---------------------------- Cause: This option (all preceeded by the "-") is unknown to "whereis". "ERROR: I've no filepattern to search for!" ------------------------------------------- Cause: "whereis" always needs a filename/pattern to search for. You only entered an option/switch. "STRANGE ERROR: Something strange happend...!" ---------------------------------------------- Cause: While descending the directory-tree, "whereis" cannot get a "lock" on a subdirectory. This error should *never* occur! Another possibility is a fault during the CD, if you enable the interactive mode (switch '-j'). "ERROR: Input must be interactive!" ----------------------------------- Cause: This error occurs only in conjunction with the "-j" (interactive) option. Perhaps you tried to run the interactive mode in background ("run whereis -j ...") or you redirected the standard-input to a non input- device ("whereis <t:tmp -j ..."). Please start again without "run" or "<". Future enhancements?! ===================== If you find this utility quite useful and better than all other "find-that-file"- utilities, and if there are no "flames", I could add some features: - a listing option. The output of date and size will then be formatted. Until this option is implemented use "list" instead and pipes. - search for date. Since/upto option like implemented in "list". In some cases it would be useful to find the files again, which you used and got today or yesterday or last week... - A faster and more compact code (perhaps with help of assembler-routines). I think this would produce much more speed, maybe about 5%. The speed depends more on your hard-disk and controller! A few words from the author... ============================== I wrote this program, because I was fed up to look for programs with my former "whereis/wo/findpath/find..." utilities: All of them had aggravating deficiencies. Either no case-independent search or not abortable, or to slow and now wildcards :-(. Because I learned C, I thought of making it better (I hope it succeeded...:-)! Because good literature is rare and I prefer the English/American originals it wasn't easy to get the amiga under control... I missed a good manual for the dos.library, but nevertheless the first working version was ready after one week (I did the work a few hours each day)... In comparison with "LookFor" (distributed on Fish-Disk 274, Author: Mark Schretlen, size: 11224 bytes), which doesn't offer any special options and requires more stack than 4000 bytes, "whereis" was faster: Scanning 3210 entries yielded on my system: LookFor: 69.46 s [lookfor >nil: test on sc1:] 3 entries found Whereis: 59.78 s [whereis >nil: sc1: test] 4 entries found Find : 61.40 s [find >nil: sc1: -name test -print] 4 entries found As you can see, the times of "find" and "whereis" are very similar. Perhaps little differences are caused by caching in buffers or other side effects. All programs were held and started from ram-disk. BTW: "whereis" runs fine with 4000 bytes of stack. LookFor requires more stack. The "LookFor" option "LookFor test on all" caused an error, because I mounted the PIPE: device. LookFor couldn't manage this! I don't want to annoy the authors of the "fnams|recurdir|mydir" utilities, but "whereis" combines *two* functions in one program! ;-) Play with "whereis" and it's features and perhaps you'll discover new applications. I hope that this utility will be placed in every programmers utility-dir to make it easier for their work (Hi Matt?:-). ** Have Fun! ** Best wishes, Roland Bless P.S.: I want to thank Matt Dillon for his great DME! Thanx Matt! All others, please excuse my poor English, but it isn't my native language. I will welcome some hints about shabby faults. -------------------------------------------------------------------------------- RELEASE-HISTORY: ---------------- V1.14 : First released ;-) version of "whereis". KNOWN BUGS: Requires FAST-RAM. Doesn't run with NOFASTMEM! V1.14a: Fixed the bug of V1.14. NOT RELEASED. V1.15: Some new useful options/switches. -a, -s, -t, -f, -d, -p -n KNOWN BUGS: -a Option (forgot a break ...:-). NOT RELEASED. V1.16: Source optimized: minimal faster, but less Code than in V1.15. Bug fixed (-a option). Errorhandling completed: No filepattern to search for... KNOWN BUGS: If there is not enough free memory, "whereis" would abort with an error message, but the allocated memory won't be freed correctly. Fixed in versions since 26-11-89. Wildcard-handling improved: "*?*??*a*c" etc. is now perfect! V1.16a: A BUG in the wildcard-handling fixed: Filenames with a space in it, were not displayed, if the '*'-wildcard was selected. Really a subtle bug! Didn't occur when the -c option was active, because then toupper() was not used. (Note: 0x020 & 0x5f == '\0') I found this bug by accident (do you often have files with a space in their name? I don't!) ALL versions till V1.16a (inclusive) were released just in a few bbs in germany (FRG). V1.17: -j option added. -p switch changed! (see option -p). Checked the break-behaviour. All ok. KNOWN BUGS: The CD to a volume killed the ":" at the end of its name. That was not like AmigaDOS did. V1.18 The little bug of 1.17 corrected. CD should work now. KNOWN BUGS: Version (15-2-90) yes, only the executable was buggy, because I linked some obscure _exit and _main modules to it. One BUG was that "whereis" did not leave your memory clean. Just a few bytes, about 20, were not freed. The second BUG: The return-code was wrong if all went ok. Instead of returning twice 0, some crazy values were returned. If you recompiled the source with +L (long integers) these bugs would not have occured. Sorry, I think the source is and was clean! My fault: I didn't test it hard enough!!!! V1.18 (27-2-90) Just a new executable. Source was not changed. See KNOWN BUGS above. V1.19 (25-05-90) New wildcard-routine. The old one was not correct! Try to search for a string like this: "A*bak*" would not match "Abatch.bak", because the "b" occurs the first time in "batch" and "bat" doesn't match "bak". But this is now corrected! Maybe it is now faster code...if you've got any trouble with pattern matching, please let me know! V1.20 (14-06-90) Killed chkabort-routine. No bug fixes. V1.21 (07-01-91) Bug fixed in date-routine. (01-01-XX) ------------------------+---------------------------------------------------+ R o l a n d B l e s s |Internet: rob@spirits.ka.sub.org | |BITNET: UKG5@DKAUNI2.BITNET | Kriegsstrasse 129 |FAX: +49211623818 BTX:0211623818-0001| 7500 Karlsruhe - FRG |---------spirits--in--the--material--world---------| voice +49 721 857328 |"They built machines that they can't control" STING| ------------------------+---------------------------------------------------+