Frozen Fish 1: Amiga

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

/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d3xx / d381 / sksh.lha / SKsh / ExtCmds.doc < prev next >

Wrap

Text File | 1990-10-20 | 51KB | 2,047 lines

External Command Reference SKsh A ksh-like Shell for the Amiga Version 1.6 (Copyright) 1989, 1990 Steve Koren October 4, 1990 Table of Contents Introduction......................................3 cat...............................................4 cmp...............................................5 cp................................................6 crc...............................................7 cut...............................................8 du................................................9 encr..............................................10 fgrep.............................................11 find..............................................13 grep..............................................17 head..............................................19 indent............................................20 join..............................................21 num...............................................22 srun..............................................23 strings...........................................24 tail..............................................26 tee...............................................27 view..............................................28 wc................................................29 window............................................30 xd................................................31 SKsh Amiga Shell Page 2 External Cmd Reference Introduction This reference manual describes each SKsh external command in a concise manner. Each page contains the following information: Name: The name of the command. Type: Always External Command for this document; may be something else in the reference manual. Default: Default parameters, if applicable. Usage: Command syntax Range: Legal values for variables or parameters About: Text describing the command, variable, etc. Example: A brief example usage. See Also: Other related commands, variables, etc. When reading the command syntax, anything in square brackets is optional. Anything followed by three dots can be repeated any number of times. A vertical bar is used to separate op- tion where one or the other, but not both, can be used. In general, 'command -a -b' is equilivant to 'command -ab'. All external commands were re-written in SKsh 1.4 to be much smaller and faster than their earlier counterparts. In 1.5 they are slightly smaller yet. SKsh Amiga Shell Page 3 External Cmd Reference ________________________________________________________________ Name: cat Type: External Command Default: n/a Usage: cat [ file ... ] Range: n/a About: cat copies the files named on the command line to its standard output. If no files are named, it copies the standard input to the standard output. The cat external command is provided as an alter- native to the builtin form; this one can copy bi- nary data as well as ASCII data and is much faster when the output is redirected to a file. To use the external cat command by default, insert the following line into your .skshrc file: unset -b cat Example: cat myfile.foo See Also: The cat command entry in Reference.doc ________________________________________________________________ SKsh Amiga Shell Page 4 External Cmd Reference ________________________________________________________________ Name: cmp Type: External Command Default: n/a Usage: cmp [ -s ] file1 file2 Range: n/a About: cmp compares two files for equality. It can be used on binary as well as textual data. cmp is fast in that if the files are not the same size, it won't even bother comparing the contents of the files. cmp normally outputs a message that indi- cates whether the files are the same, different, or one is shorter than the other. If the -s op- tion is used, compare does not output this infor- mation, but simply returns a zero exit status if the files were the same, or non-zero if they were not. Example: if cmp -s file1 file2 then echo 'file1 is the same as file2' else echo 'file1 is different than file2' fi See Also: ________________________________________________________________ SKsh Amiga Shell Page 5 External Cmd Reference ________________________________________________________________ Name: cp Type: External Command Default: n/a Usage: cp [ -nuv ] file { file | dir } cp [ -nruv ] { file | dir } ... dir Range: n/a About: cp copies files from one place to another, option- ally renaming them in the process. If the desti- nation is a directory, the files have the same name in the destination directory. If more than one file is copied, the destination must be either a directory or nonexistant. If it is nonexistant, it is created as a directory. The -r flag causes cp to perform a recursive copy. The -v flag prints the name of each file as it is copied. The -n flag causes cp NOT to duplicate file modi- fication times and protection flags on the desti- nation files. If you wish to make this the de- fault behavior, use this alias: alias cp='$(which cp) -n' cp will reset the AmigaDos archive bit whether or not the -v flag is used. The -u flag causes cp to operate in "update" mode; only files with a newer timestamp than their asso- ciated destination are copied. Example: cp my_file1 m_file2 my_file3 my_directory Warnings: The -c (clone) flag was obsoleted in SKsh 1.4. It is still accepted for backward compatibility; how- ever, it is ignored. Use the -n option to turn off the clone behaviour. The cp command was changed to an external binary in SKsh 1.4. It used to be a builtin. See Also: mv ________________________________________________________________ SKsh Amiga Shell Page 6 External Cmd Reference ________________________________________________________________ Name: crc Type: External Command Default: n/a Usage: crc [ -q ] file1 [ file2 ] ... Range: n/a About: crc generates several 32 bit values which are com- puted from a file's contents. These values can be used to check the integrity of files which are transfered over a medium of questionable reliabil- ity (such as phone lines). If the -q switch is given, crc will not print the file name. This is useful in scripts to check the validity of a file by comparing crc output to known good values. Example: crc a_file another_file See Also: ________________________________________________________________ SKsh Amiga Shell Page 7 External Cmd Reference ________________________________________________________________ Name: cut Type: External Command Default: n/a Usage: cut [ -flist [ -dchar ] | -clist ] [ file ... ] Range: n/a About: Cut is used for making vertical slices though a file based on character position or on fields de- limited by a defined character. It can also be used to re-order characters or fields within a file. The -c option cuts based on character positions in the line. For example, "-c1,5-10,20" would copy characters one, five though ten, and twenty from each input line to the output line. If the list begins with a dash (for example, "-c-10") the first item is used implicitly (1 though 10 in this case). Characters beyond the end of line are ignored. The -f option cuts based on field position within a line. Fields are separated by the tab character by default, but this can be changed with the -d option. For example, "-d:" would use colon sepa- rated fields. Repeated strings of the field sepa- rator indicate empty fields. Fields beyond the last in the record are ignored. No space may occur between the -d option and the field separator character, or between the -f or -c options and the list. Example: cut -c1-10,15,20-50 myfile.txt cut -f1,3,5-7 -d: myfile1.txt See Also: ________________________________________________________________ SKsh Amiga Shell Page 8 External Cmd Reference ________________________________________________________________ Name: du Type: External Command Default: n/a Usage: du [ -dkst ] dir ... Range: n/a About: du prints disk usage information for a set of directories. For each directory listed on the command line, the subtree rooted at that point is searched in a depth-first manner. du adds all the file sizes, and for each directory, prints 1) the directory name, 2) the total disk usage for files in this directory, and 3) the total disk usage for the subtree rooted at this directory. The following options are available: -k Print disk usage in 1024 byte kilobytes instead of the default bytes. -s Summary mode; print disk usage only for root directories listed on the command line. This option omits the display for any sub-directories, but still must exam- ine the entire directory subtree to find the total disk usage. -d Omit the first disk usage number (the to- tal for this directory only). -t Omit the second disk usage number (the to- tal for the subtree rooted at this direc- tory). If both -t and -d are used, only directory names are printed. Example: du devs: ram: du -s devs: Warnings: The -k option rounds to the nearest kilobyte. For example, a 1023 byte file is printed as 1K, and a 511 byte file is printed as 0K. This means that the rooted subtree disk usage count may not be the sum of the directory disk usage counts for all subdirectories. See Also: info ________________________________________________________________ SKsh Amiga Shell Page 9 External Cmd Reference ________________________________________________________________ Name: encr Type: External Command Default: n/a Usage: encr { -d|-e } key { infile | - } { outfile | - } Range: 4 <= strlen(key) <= max parameter length About: encr encrypts (-e) and decrypts (-d) files, or standard input and output if the file name is given as a dash. The key value must be the same for the encrypt and decrypt; otherwise, garbage will result. The key may be of any passable length. Longer keys will result in a more secure encryption. The encrypted data will in most cases not be ASCII data. However, this can be an advantage in that encr can be used to encrypt binary as well as ASCII data. If encrypted data is to be compressed, the com- press operation should be performed before the data is encrypted, not after. This is because the encrypted data will appear random, and hence be difficult to compress by the standard algorithms. encr does not use the DES algorithm, as code based on that algorithm is not shippable outside of the United States. (This is a bit paranoid if you ask me, but no one did). For obvious reasons, I'm not going to describe the encr algorithm here. The algorithm should be plenty secure enough to dis- courage casual perusal of encrypted data. It is probably not secure enough to keep data from a dedicated cryptoanalyst, or perhaps even from someone who is willing to closely examine a disas- sembly of the program code. I have provided a small file with this release of SKsh which con- tains some encrypted english text; I would very much like to hear if anyone manages to find out what it says. The file is called "crypted_data". Example: encr -e mykey plainfile encryptedfile encr -d mykey encryptedfile plainfile See Also: ________________________________________________________________ SKsh Amiga Shell Page 10 External Cmd Reference ________________________________________________________________ Name: fgrep Type: External Command Default: n/a Usage: fgrep -[vxcilns] [-f pfile] [-e] pattern [ file ... ] Range: n/a About: fgrep provides a fast way to search for text pat- terns in a set of files. It is similar to, al- though more limited but faster than, grep. fgrep searches for the indicated pattern in the indicated set of files, if present, or the stan- dard input, if not. An fgrep pattern is extremely limited; it can be either a string constant or a set of string constants separated by percent signs. For example, these are valid fgrep state- ments: fgrep my_routine *.c fgrep 'this%or%that' my_file my_other_file In the second example, fgrep searches for lines containing any of the three strings. There are a large number of options availble which modify the actions of fgrep: -c Print only a count of matching lines for each file. If the 'v' option is used with the 'c' option, a count of non-matching lines is printed. -e Use the next argument as the pattern. This is useful to search for patterns beginning with a dash. -f Use the next argument as a file which con- tains a newline separated list of values. This file is read and used in place of the command line pattern. For example, the fol- lowing two examples are equivalent: fgrep 'foo%bar' myfile echo "foo" >temp; echo "bar" >>temp fgrep -f temp myfile SKsh Amiga Shell Page 11 External Cmd Reference -i Ignore case in the search. Normally, fgrep is case sensitive. -l Print only the names of files which containg the given pattern. This is fast; if fgrep finds the pattern anywhere in the file, it will stop looking and proceed to the next file. This can save time for large files where the task is to discover which files contain the given pattern. -n Print the line number before each matching line. -s Print nothing. Return an exit code of 0 (true) if any file contained the pattern, or 1 (false) if no files contained the pattern. -v Invert the search. Lines which do not con- tain the pattern are printed. -x Lines must match the pattern exactly, not simply contain it. Example: if grep -s my_pattern my_file then echo 'my_file contains my_pattern' fi Warnings: Patterns which contain '%', spaces, or other spe- cial characters should be quoted to avoid being interpreted by the shell. The '%' character is used to separate strings in- stead of a newline as in Un*x, as there is a prob- lem in AmigaDos passing parameters containing newlines to external commands. See Also: grep ________________________________________________________________ SKsh Amiga Shell Page 12 External Cmd Reference ________________________________________________________________ Name: find Type: External Command Default: n/a Usage: find paths [ -print ] [ -exec command ] [ -cmd command ] [ -type {d|f} ] [ -hidden ] [ -depth ] [ -case ] [ -blocks n ] [ -bigger n ] [ -smaller n ] [ -ver | -v ] [ -comment pattern ] [ -name pattern ] [ -path pattern ] [ -quiet ] [ -newer { file | date [ time ] } ] [ -older { file | date [ time ] } ] Range: n/a About: Find recursively walks the directory hierarchy, applying certain tests to files and performing a defined action on files which pass the tests. Find may be given one or more path parameters fol- lowed by zero or more switches. Usually at least one of the following two switches is used: -print Print the files for which the given tests are true. Files and directories are listed to standard output, one per line. If the paths given to find are absolute, the out- put will be also. If the input paths are relative, the output will be relative to the same location. -cmd The first argument following this switch is used as a format string for the output. Any occurrences of "%s" (without the quotes) are replaced by the output path name. Results are sent to standard output. This is of- ten useful to build a script file for later interpretation by the shell. The other switches indicate conditions which are "anded" together. A file or directory must meet all conditions to be selected. If patterns are given to any switches, they must be quoted. -type The first argument following this switch is either "d", which selects only directories, or "f", which se- lects only files. SKsh Amiga Shell Page 13 External Cmd Reference -name The file name must match the pattern given as the next parameter. Only the file portion (the basename) of the path must match. -path Similar to -name, but the given pat- tern must match the entire path, not just the file portion. Slashes ("/") are not treated specially. -comment A file's comment, if it exists, must match the pattern given as the next parameter. -case Normally all pattern matching is case insensitive. This switch will make it case sensitive. -depth Causes find to perform a depth-first scan. Normally directories are listed before their contents; this switch reverses that order. -blocks The following parameter, which must be numeric, is treated as a block size. All files containing this num- ber of blocks are selected. -bigger The following parameter is a byte count. All files having this many bytes or more are selected. -smaller Similar to -bigger, but selects files having this byte count or less. -newer Has several forms. If the following parameter is a file name, then all files which are newer (have a later datestamp) than this file are selected. If followed by one param- eter which is a date in AmigaDos dd- mmm-yy format, files newer than this date are selected (files created any- time after 12:00am are considered to be newer). If given two following arguments, the first of which is a date in the above format, and the second of which is a time in hh:mm:ss format, then files newer than this are selected. -older Similar to -newer. SKsh Amiga Shell Page 14 External Cmd Reference -quiet Normally find will print an error message if it is unable to examine a file or directory's entry. This might happen, for example, if another process has this file open for writing. This switch will cause find to silently skip these files; this is useful with the -cmd option. -hidden Normally files which are "hidden" (ie, have the +h bit set) are not seen by find. This switch causes find to list these files. -exec The following parameter is taken as a command. All occurrences of "%s" are replaced by the file or directory name, and the string is then executed. If the resulting command returns successfully (ie, with exit code 0), then the file or directory is selected. Otherwise, it is rejected. Since this operation can be slow (invoking another program for each path), it is invoked last and only if all other tests have succeeded. For example, if used in conjunction with "-blocks", only files passing the "-blocks" test will be given to "-exec". It is recom- mended that -exec be used only with some other qualifier to reduce the number of times the command must be called. Programs invoked from -exec must be specified as a complete path. -ver or -v Prints the version ID of find. Example: # list all files under /usr and /misc: find /usr /misc -print # list all files under /usr/appl newer than # ram:myfile: find /usr/appl -newer ram:myfile -print # list all files under /pd/src ending in ".h" and having a non-null file comment: find /pd/src -name '*.h' -comment '?*' -print SKsh Amiga Shell Page 15 External Cmd Reference # run "view -t" on all files under /misc: find /misc -type f -print | while read fspec do view -t $fspec done # another way to do that above: find /misc -cmd -type f "/bin/view -t %s" >myscr source myscr # find all files under /foo bigger than 10000 # bytes, smaller than 50000 bytes, and containing # the string "blee": find /foo -print -exec "sys:bin/fgrep blee %s" \ -bigger 10000 -smaller 50000 Limits: In this version of find, only one of each qualifier switch may be given. For example, only one -name switch can be used. This limitation may be removed in a future version of find. In spite of this limit, multiple directories may still be searched. See Also: ________________________________________________________________ SKsh Amiga Shell Page 16 External Cmd Reference ________________________________________________________________ Name: grep Type: External Command Default: n/a Usage: grep -[vxcilns] [-f pfile] [-e] pattern [ file ... ] Range: n/a About: grep provides a way to search for text patterns in a set of files. It is similar to, although more powerful but slower than, fgrep. grep searches for the indicated pattern in the in- dicated set of files, if present, or the standard input, if not. A grep pattern is a limited regu- lar expression. An explaination of regular ex- pressions is beyond the scope of this document; however, it should be noted that although they ap- pear similar to wildcards, they are much different (and more powerful). There are a large number of options availble which modify the actions of grep: -c Print only a count of matching lines for each file. If the 'v' option is used with the 'c' option, a count of non-matching lines is printed. -e Use the next argument as the pattern. This is useful to search for patterns beginning with a dash. -f Use the next argument as a file which con- tains a one-line regular expression. There can only be one regular expression in this version of grep, so this option is currently of limited use. However, if grep is extended to permit multiple expressions, the 'f' op- tion will become more useful. -i Ignore case in the search. Normally, grep is case sensitive. -l Print only the names of files which containg the given pattern. This is fast; if grep finds the pattern anywhere in the file, it will stop looking and proceed to the next file. This can save time for large files SKsh Amiga Shell Page 17 External Cmd Reference where the task is to discover which files contain the given pattern. -n Print the line number before each matching line. -s Print nothing. Return an exit code of 0 (true) if any file contained the regular ex- pression, or 1 (false) otherwise. -v Invert the search. Lines which do not con- tain the regular expression are printed. -x The expression must be found at the beginning of a line. Example: if grep -s my_pattern my_file then echo 'my_file contains my_pattern' fi Warnings: Patterns which contain '*', '.', spaces, or other special characters should be quoted to avoid being interpreted by the shell. Be wary of the difference in the 'x' option be- tween fgrep and grep. fgrep often more useful than grep because of its greater speed and smaller size. This is most noticable on fast devices such as ram or hard disks. See Also: fgrep ________________________________________________________________ SKsh Amiga Shell Page 18 External Cmd Reference ________________________________________________________________ Name: head Type: External Command Default: num = 10 Usage: head [ -num ] [ file ... ] Range: 0 <= num About: head prints the first num lines of each named file, or the standard input if no files are indicated. If num is not explicitly set, it has a default value of 10. Example: head -5 my_file.c my_other_file.c See Also: tail ________________________________________________________________ SKsh Amiga Shell Page 19 External Cmd Reference ________________________________________________________________ Name: indent Type: External Command Default: char = space num = 4 Usage: indent [ -num ] [ -cchar ] [ file ... ] Range: n/a About: Indent inserts the defined character (a space by default) a given number of times (4 by default) at the beginning of every line of a file which does not contain only a newline. That is, empty lines are left alone. Example: indent -5 myfile.txt See Also: ________________________________________________________________ SKsh Amiga Shell Page 20 External Cmd Reference ________________________________________________________________ Name: join Type: External Command Default: n/a Usage: join [ -a ] source1 [ source2 ... ] destination Range: n/a About: The join command concatinates binary or ASCII data from multiple files into a single file, optionally appending the data to the destination file if the -a flag is set. The destination file is the last one given. Example: join file1 file2 dest_file See Also: ________________________________________________________________ SKsh Amiga Shell Page 21 External Cmd Reference ________________________________________________________________ Name: num Type: External Command Default: num = 4 Usage: num [ -digits ] [ -r ] [ file ... ] Range: 2 <= digits <= 8 About: num prints ASCII files, prefixing each line in the file with its line number. By default, 4 digit line numbers are used, but this can be changed from 2 to 8 digits numbers with the command line switch. Also by default, num resets the line number at the beginning of each file. To use consecutive line numbers for all files, use the "-r" switch. With that option selected, the line count is not reset for each file. Example: num -6 -r myfile1.c myfile2.c See Also: ________________________________________________________________ SKsh Amiga Shell Page 22 External Cmd Reference ________________________________________________________________ Name: srun Type: External Command Default: stk = 4000 pri = 0 Usage: srun [ -i file ] [ -o file ] [ -s stk ] [ -p pri ] program [ args ] Range: 4000 <= stk -31 <= pri <= 31 About: srun was created to overcome certain deficiencies in the AmigaDos run command. srun is most useful in scripts or functions, although it can also be used from the command line. It allows you to specify an input file, output file, stack size, and priority for a command which is run in the background. Standard input and output cannot be re-directed with the AmigaDos run command (for ex- ample, if standard output is redirected, the out- put file will contain only "[CLI n]"). The srun command is very useful in functions such as the one given below (very much simplified from one given in the Stuff.sksh file). The program name given to srun must be a complete path. This can be obtained in SKsh via: $(which -s prog) srun will report an error if it is unable to ex- ecute the program or unable to open and input or output file. Example: function zmore { srun -o pipe:tmp $(which zoo) -print "$1" "$2" more pipe:tmp } See Also: run ________________________________________________________________ SKsh Amiga Shell Page 23 External Cmd Reference ________________________________________________________________ Name: strings Type: External Command Default: num = 6 Usage: strings [ -num ] [ file ... ] Range: 0 <= num About: strings searches the named files for strings of at least num consecutive printable characters. If found, it prints them. If num is not set, it de- faults to 6. Example: strings -10 my_file.o binary_file See Also: ________________________________________________________________ SKsh Amiga Shell Page 24 External Cmd Reference SKsh Amiga Shell Page 25 External Cmd Reference ________________________________________________________________ Name: tail Type: External Command Default: num = 10, '-' option Usage: tail [ -num | +num ] [ file ... ] Range: 0 <= num <= 32000 About: tail prints the last num lines of each named file, or the standard input if no files are named. If a '+' precedes num instead of a '-', tail instead skips num lines and prints the rest of the file. In SKsh 1.4, the algorithm used by tail was changed. If run on a file, it will now seek to the end of the file and read backwards until it encounters the proper line. This means that run- ning tail on a large file is now nearly instanta- neous; previously, it would read in the entire file. Example: tail -15 my_file.c my_other_file.c See Also: head ________________________________________________________________ SKsh Amiga Shell Page 26 External Cmd Reference ________________________________________________________________ Name: tee Type: External Command Default: n/a Usage: tee [ -a ] [ file ... ] Range: less than 32 files About: tee copies its standard input to its standard out- put, and also to any named files. The old con- tents of the files are overwritten unless the ap- pend (-a) flag is used. With no arguments, tee simply copies its input to its output. Example: fgrep foo my_file | tee save_foo | wc -c See Also: _______________________________________________________________ SKsh Amiga Shell Page 27 External Cmd Reference ________________________________________________________________ Name: view Type: External Command Default: n/a Usage: see View.doc Range: n/a About: view is a command which allows other commands to be called based on the type of a given file. See the View.doc manual for a detail description of this command. Example: view myfile my_otherfile See Also: ________________________________________________________________ SKsh Amiga Shell Page 28 External Cmd Reference ________________________________________________________________ Name: wc Type: External Command Default: n/a Usage: wc [ -hcwlqt ] [ file ... ] Range: n/a About: wc is a utility which counts characters, words, or lines in a given series of files (or the standard input, if no files are indicated). It normally produces information on all three counts, preceded by a title for each column. If the c, w, or l flags are set, only information on characters, words, or lines is printed. (These can be com- bined; for example 'wc -cl'). If the q flag is set, wc does its work quietly; that is, it leaves out titles and file names, only reporting the ac- tual counts. The t flag can be used to obtain a total at the end, and the h flag prints a helpful usage message. Example: if [ $(wc -lq my_file) -lt 10 ] then echo "There must be at least 10 lines" fi See Also: ________________________________________________________________ SKsh Amiga Shell Page 29 External Cmd Reference ________________________________________________________________ Name: window Type: External Command Default: n/a Usage: window [ -back ] [ -front ] [ -title ] [ -pos [x,y] ] [ -size [x,y] ] [ -scrsize ] [ -wmouse ] [ -smouse ] Range: n/a About: window is a command which allows parameters of the current shell window to be modified or examined. The -back and -front flags cause the window to be sent to the back or front. The -title flag causes the current window title to be printed. The -pos flag with no following parameters can be used to find the current x and y positions of the window. With a comma separated set of numbers, it moves the window to that position if possible. Simi- larly, the -size parameter either reports the size of the current window in pixels, or resizes the window to that size if possible. The -scrsize flag reports the current size of the screen con- taining this window, and the -smouse and -wmouse flags report the cursor position relative to the screen or window. With no parameters, the window command prints a helpful usage message. Note that this usage mes- sage contains one additional option which can be included after the -title flag to change the win- dow title to a set value. However, this is not actually permitted by AmigaDos, and although it works now, it may cause problems, and its use is not recommended. Use at your own risk. Example: # move window to back and upper left hand corner window -back -pos 0,0 See Also: ________________________________________________________________ SKsh Amiga Shell Page 30 External Cmd Reference ________________________________________________________________ Name: xd Type: External Command Default: n/a Usage: xd [ file ... ] Range: n/a About: xd (hex dump) prints a hexadecimal dump of each named file, or the standard input if no files are named. It prints the hex address of the current offset as 8 digits, then a hex dump of 16 bytes separated into groups of 2 bytes, then an ASCII rep- resentation of the 16 bytes, or '.' if the byte is not a printable character. Example: xd any_old_file See Also: ________________________________________________________________ SKsh Amiga Shell Page 31 External Cmd Reference