home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 11 Util / 11-Util.zip / RH2OS2.ZIP / RH.MAN < prev    next >
Text File  |  1990-06-26  |  14KB  |  411 lines
  1. NAME
  2.      rh - recursive file locater (rawhide) >> VERSION 2 <<
  3.  
  4. SYNOPSIS
  5.      rh [ -vhlr ] [ -f filename ]
  6.           [ -e expression ] [ -x command ] file...
  7.  
  8. DESCRIPTION
  9.      Rh recursively searches the file system starting at each
  10.      given file for files that make a C expression true.  If no
  11.      files are listed, the current working directory is used.
  12.  
  13.      Expressions for rh can come from the command line (with the
  14.      -e option), a file (with the -f option), or from the stan-
  15.      dard input (the default).  The basic form of an rh expres-
  16.      sion is a C expression which may optionally define and or
  17.      call user defined functions. These C expressions may contain
  18.      constants, variables, and all the usual C operators.
  19.  
  20.      Constants are either numeric or symbolic.  Symbolic con-
  21.      stants are based on the constants defined in the file
  22.      /usr/include/sys/stat.h; only the useful constants are
  23.      implemented.  The ``S_'' prefix from the symbol name is
  24.      omitted.  (eg. S_IFMT would used as IFMT).
  25.  
  26.      Variables are symbols that specify a field in the stat
  27.      structure (e.g., st_size, st_mode) or some other attribute
  28.      of the file.  For each file examined by rh, these internal
  29.      variables are updated to match the current file.  For con-
  30.      venience, the ``st_'' prefix is dropped from variable names.
  31.  
  32.      Functions are a means of associating a C expression with a
  33.      function name.  This allows complex expressions to be easily
  34.      composed from simpler ones.  The value of a function call is
  35.      the value of the expression represented by the function. For
  36.      example:
  37.  
  38.              foo(x)
  39.              {
  40.              return( x-1 );
  41.              }
  42.  
  43.      If the above function were given to Rh, it would define a
  44.      function that could be used later. If foo were called with
  45.      667, then the value of the call to foo would be equal to
  46.      666.
  47.  
  48. OPTIONS
  49.      Rh options can appear in any order; multiple options can be
  50.      given within the same argument.
  51.  
  52.      -r   Prevents rh from recursively searching for files.
  53.  
  54.      -l   Normally rh prints each matching filename on a line by
  55.           itself.  The -l option causes the matching files' per-
  56.           mission modes and sizes to be displayed as well, in a
  57.           format similar to that of the ls(1) command.
  58.  
  59.      -h   Causes rh to display a help message.  The message
  60.           explains the command line usage, a list of available
  61.           constants and variables and a list of valid operators.
  62.           Rh then continues as though the -h option were not
  63.           present.
  64.  
  65.      -f filename
  66.           Uses filename as the name of a file containing a rh
  67.           expression. Functions may also be defined in this file.
  68.  
  69.      -e expression
  70.           Uses expression as the expression that will be used for
  71.           the file search.  Since many of the operators are also
  72.           shell meta-characters and since rh expressions may con-
  73.           tain spaces, it is strongly recommended that the
  74.           expression be enclosed in single quotes, ''. If both
  75.           the -e and -f options occur together then the -f option
  76.           is processed FIRST, followed by the -e option. This
  77.           means that an expression specified with the -e option
  78.           may use functions defined from the -f file.
  79.  
  80.      -v   Verbose. Causes the -l option to output more informa-
  81.           tion and the -x option to print out the command exe-
  82.           cuted and the return value.
  83.  
  84.      -x command
  85.           Execute command using system(3) for each matching file.
  86.           The string command may contain a %s which will be sub-
  87.           stituted with the full path name. A %S (uppercase 'S')
  88.           will be substituted with the base name. For example,
  89.           given the file /etc/passwd the values for %s and %S
  90.           would be: /etc/passwd and passwd, respectively.
  91.  
  92.     MS-DOS and OS/2 only:
  93.       %f equivalent to %s
  94.       %p path component
  95.       %n base name without extension
  96.       %e extension
  97.  
  98. USAGE
  99.      Rh grammer
  100.      This is the grammer that rh will accept.
  101.  
  102.      <program> ::=
  103.                      <function list> <expression> EOF
  104.                      | <function list> <expression> ;
  105.  
  106.      <function list> ::=
  107.                      <function list> <function>
  108.                      | <function>
  109.                      | /* empty */
  110.  
  111.      <function> ::=
  112.                      <function heading> { RETURN <expression> ; }
  113.  
  114.      <function heading> ::=
  115.                      IDENTIFIER
  116.                      | IDENTIFIER ( )
  117.                      | IDENTIFIER ( <idlist> )
  118.  
  119.      <idlist> ::=
  120.                      <idlist> , IDENTIFIER
  121.                      | IDENTIFIER
  122.  
  123.      <expression> ::=
  124.                      <expression> ? <expression> : <expression>
  125.                      | <expression> || <expression>
  126.                      | <expression> && <expression>
  127.                      | <expression> | <expression>
  128.                      | <expression> ^ <expression>
  129.                      | <expression> & <expression>
  130.                      | <expression> == <expression>
  131.                      | <expression> != <expression>
  132.                      | <expression> < <expression>
  133.                      | <expression> > <expression>
  134.                      | <expression> <= <expression>
  135.                      | <expression> >= <expression>
  136.                      | <expression> >> <expression>
  137.                      | <expression> << <expression>
  138.                      | <expression> + <expression>
  139.                      | <expression> - <expression>
  140.                      | <expression> * <expression>
  141.                      | <expression> / <expression>
  142.                      | <expression> % <expression>
  143.                      | ~ <expression>
  144.                      | ! <expression>
  145.                      | - <expression>
  146.                      | <factor>
  147.  
  148.      <factor> ::=
  149.                      ( <expression> )
  150.                      |    NUMBER
  151.                      |    <function call>
  152.                      |    IDENTIFIER
  153.                      |    [ <date spec> ]
  154.                      |    STRING
  155.  
  156.      <function call> ::=
  157.                      IDENTIFIER
  158.                      | IDENTIFIER ( <exprlist> )
  159.                      | IDENTIFIER ( )
  160.  
  161.      <exprlist> ::=
  162.                      <exprlist> , <expression>
  163.                      | <expression>
  164.  
  165.      <datespec> ::=
  166.                      NUMBER / NUMBER / NUMBER
  167.  
  168.      Search order:
  169.      Rh initally looks for a $HOME/.rhrc and if it exists it will
  170.      be read in. Next, any file specified by the -f option is
  171.      read followed by any expression specified with the -e
  172.      option. If after all that, an expression, defined outside of
  173.      a function, has not been encountered then stdin will be read
  174.      for such an expression.  An error will result if no expres-
  175.      sion has been encountered.
  176.  
  177.      A $HOME/.rhrc will usually contain function definitions that
  178.      will be accessable for the user when they enter in a search
  179.      expression.
  180.  
  181.      The valid constants are:
  182.  
  183.      NOW  This constant is set to the current time at the start
  184.           of rh. It is used to make comparisons with atime, ctime
  185.           and mtime.
  186.  
  187.      days This is equal to the number of seconds in a day.
  188.  
  189.      hours
  190.           Number of seconds in an hour.
  191.  
  192.      weeks
  193.           Number of seconds in a week.
  194.  
  195.      IFBLK IFDIR IFLNK IFMT IFREG IFSOCK ISGID ISUID ISVTX
  196.           see stat(2) for an explanation.
  197.         MS-DOS and OS/2:
  198.           IFDIR IFMT IFREG IFCHR ISYS IHID IMOD IREAD IWRITE IEXEC
  199.  
  200.      The valid variables are:
  201.  
  202.      depth
  203.           This variable is set to the relative depth in the
  204.           directory search that the current file is at.
  205.  
  206.      strlen
  207.           This is set to the length of the filename. For example
  208.           strlen would be equal to 4 given the file: "/tmp/core"
  209.           because "core" is 4 characters long.
  210.  
  211.      prune
  212.           This varible always returns 0, but as a side-effect
  213.           causes the search path to be "cut-short" when
  214.           evaluated. This can be used to prune the directory
  215.           search.  prune is usually used with the ?: operator to
  216.           conditionally evaluate the prune variable.
  217.  
  218.      atime,ctime,dev,gid,ino,mode,mtime,nlink,rdev,size,uid
  219.           see stat(2) for an explanation.
  220.  
  221.      The valid C operators are:
  222.  
  223.      ! ~ - * / % + < <= > >= == != & ^ | << >> && || ?:
  224.  
  225.      Operator precedence, associativity and semantics are the
  226.      same as in C.
  227.  
  228.      Special operators:
  229.  
  230.      $username
  231.           This operator evaluates to the integer user id of user-
  232.           name. As a special case the symbol $$ evaluates to the
  233.           uid of the user currently running rh.
  234.  
  235.      "*.c"
  236.           This operator evaluates to true if the current filename
  237.           matches the quoted expression, which is a shell glob-
  238.           bing pattern.  The recognized metacharacters are:
  239.  
  240.           ``*''
  241.             to match any number of characters, including zero
  242.             (except that, as in the shell, it does not match a
  243.             leading ``.'');
  244.  
  245.           ``?''
  246.             to match any single character (except for a leading
  247.             ``.'');
  248.  
  249.           ``[SET]''
  250.             to match any character in the given set (ranges can
  251.             be included);
  252.  
  253.           ``[^SET]''
  254.             to match any character not in the given set;
  255.  
  256.           ``\\''
  257.             to escape the special meaning of any of the above
  258.             metacharacters.
  259.  
  260.      When doing comparisons, only the base name is examined, not
  261.      leading paths.
  262.  
  263.      [yyyy/mm/dd]
  264.           The date enclosed in the brackets, ``[]'', will evalu-
  265.           ate to a number of seconds past January 1, 1970, which
  266.           is suitable for comparing with atime, mtime or ctime.
  267.           The year cannot be abbreviated to its last two digits.
  268.  
  269.      The special operators have higher precedence than the C
  270.      operators.
  271.  
  272.      Lexical conventions:
  273.  
  274.      Numbers may be entered in octal by preceding them with a
  275.      leading zero.  Otherwise numbers are taken to be in decimal.
  276.  
  277.      Text enclosed in /* and */ will be ignored. This can be used
  278.      for commenting rh expression files.
  279.  
  280.      The start expression may be terminated by either a ``;'' or
  281.      the end of the file or argument.
  282.  
  283. EXAMPLES
  284.      The following are examples of rh expressions.
  285.  
  286.              (mode & 022) && (uid == $joe );
  287.  
  288.      Matches all files that have uid equal to username ``joe''
  289.      and are writable by other people.
  290.  
  291.              !uid && (mode & ISUID ) &&
  292.              (mode & 02);
  293.  
  294.      Matches all files that are owned by root (uid==0) and that
  295.      have set-uid on execution bit set, and are writable.
  296.  
  297.              (size > 10*1024) && (mode & 0111) &&
  298.              (atime <= NOW-24*3600);
  299.  
  300.      Finds all executable files larger than 10K that have not
  301.      been executed in the last 24 hours.
  302.  
  303.              size < ( ("*.c") ? 4096 : 32*1024 );
  304.  
  305.      Finds C source files smaller than 4K and other files smaller
  306.      than 32K.  No other files will match.
  307.  
  308.              !(size % 1024);
  309.  
  310.      Matches files that are a multiple of 1K.
  311.  
  312.              mtime >= [1982/3/1] && mtime <= [1982/3/31];
  313.  
  314.      Finds files that were modified during March, 1982.
  315.  
  316.              strlen >= 4 && strlen <= 10;
  317.  
  318.      This expression will print files whose filenames are between
  319.      4 and 10 characters in length.
  320.  
  321.              depth > 3;
  322.  
  323.      Matches files that are at a RELATIVE depth of 3 or more.
  324.  
  325.              ( "tmp" || "bin" ) ? prune : "*.c";
  326.  
  327.      This expression does a search for all "*.c" files, however
  328.      it will not look into any directories called "bin" or "tmp".
  329.      This is because when such a filename is encountered the
  330.      prune variable is evaluated, causing further searching with
  331.      the current path to stop. The general form of this would be:
  332.  
  333.              ("baddir1" || "baddir2" || ... || "baddirn") ?
  334.                      prune : <search expr>;
  335.  
  336. ADVANCED EXAMPLES
  337.      The following examples show the use of function definitions
  338.      and other advanced features of Rh.
  339.       Consider:
  340.  
  341.              dir()
  342.              {
  343.              return ( (mode & IFMT) == IFDIR );
  344.              }
  345.  
  346.      This declares a function that returns true if the current
  347.      file is a directory and false otherwise. The function
  348.  
  349.      dir now may be used in other expressions.
  350.  
  351.              dir() && !mine();
  352.  
  353.      This matches files that are directories and are not owned by
  354.      the user. This assumes the user has written a mine() func-
  355.      tion. Since dir and mine take no arguments they may be
  356.      called like:
  357.  
  358.              dir && !mine;
  359.  
  360.      Also when declaring a function that takes no arguments the
  361.      parenthesis may be omitted. For example:
  362.  
  363.              mine
  364.              {
  365.              return uid == $joe;
  366.              }
  367.  
  368.      This declares a function mine, that evaluates true when a
  369.      file is owned by user name 'joe'. An alternate way to write
  370.      mine would be:
  371.  
  372.              mine(who)
  373.              {
  374.              return uid == who;
  375.              }
  376.  
  377.      This would allow mine to be called with an argument, for
  378.      example:
  379.  
  380.              mine( $sue ) || mine( $joe );
  381.  
  382.      This expression is true of any file owned by user name 'sue'
  383.      or 'joe'.  Since the parenthesis are optional for functions
  384.      that take no arguments, it would be possible to define func-
  385.      tions that can be used exactly like constants, or handy mac-
  386.      ros. Suppose the above definition of dir was placed in a
  387.      users $HOME/.rhrc Then the command:
  388.  
  389.              rh -e dir
  390.  
  391.      would execute the expression 'dir' which will print out all
  392.      directories.  Rh functions can be recursive.
  393.  
  394. FILES
  395.      $HOME/.rhrc
  396.  
  397. SEE ALSO
  398.      chmod(1), find(1), ls(1), stat(2)
  399.  
  400.      The C programming language.
  401.  
  402. AUTHOR
  403.      Ken Stauffer (University of Calgary)
  404.  
  405.      stauffer@sixk
  406.  
  407. BUGS
  408.      The date operator should also allow for time to be entered.
  409.      The date operator can be off by a day, if the time on the
  410.      file is close to midnight.
  411.