packages icon



 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



 NAME
      plod - keep a log of your work

 SYNOPSIS
      plod  [ -s ] [ -f file ] [ one line message ]
      plod  [ -s ] [ -f file ] -C|-E|-P|-V [ logfile [ key ]]
      plod  [ -s ] [ -f file ] -g|-G pattern [ logfile [ key ]]

 DESCRIPTION
      PLOD is a tool developed to help System/Network Administrators (and
      others) keep track of the work that they do.  Good logs are useful
      both as a personal reference and to show to your management on a
      regular basis or around performance review time. By default, logs will
      be stored in an encrypted format in the directory $HOME/.logdir, but
      this behavior is completely customizable (see ENVIRONMENT and
      CUSTOMIZATION below).

      The first form of the command will enter a short message on the
      command line into your log file.  If no message is present on the
      command line, a date/time stamp will be printed and PLOD will go into
      an interactive mode reminiscent of BSD mail.  Many tilde escape
      sequences are supported (see COMMANDS below or type ~h or ~? within
      interactive mode).  Enter a period on a line by itself to end your log
      entry.

      The second mode allows you to review or edit your old log files.  The
      -P option invokes the default PAGER defined in the PLOD source, or as
      defined in your environment, on the current log file.  The -E and -V
      flags invoke EDITOR and VISUAL respectively.  The -C option will
      simply dump the current log file to the standard output.  This is
      useful for piping your log file to other commands, such as lpr.  Older
      log files may be accessed by specifying a file name and optional
      encryption key on the command line.

      The third mode allows you to search your logs for a particular
      pattern.  The -g flag specifies a case-insensitive match, while -G
      does a case sensitive search.  The pattern may be any valid Perl
      regular expression.  Don't forget to quote the pattern to protect any
      special characters from the shell.

      In any mode, the -f flag allows the user to specify a different
      startup file than the default ($HOME/.plodrc).  The -s flag tells PLOD
      to prompt the user for their encryption key.  When making a one-line
      log entry, the -f and -s options must appear first on the command
      line.


 ENVIRONMENT
      PLOD supports a number of variables which can be modified to customize
      its behavior.  The values of these variables may be changed by editing
      PLOD directly, by assignment in a system-wide startup file, by



                                    - 1 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



      creating an environment variable, or by assignment in the user's
      startup file (see CUSTOMIZATION below).  PLOD recognizes the following
      environment variables:

      SEPARATOR
          A string used to separate one entry from another in the log file.
          This string must be constant throughout the entire file or the -g
          and -G command line options will not work correctly.  Default is
          ----- (five dashes).

      STAMP
          The time/date stamp entered into every log entry.  Set this to
          null if you do not wish to datestamp your logs.  Default is
          MM/DD/YY, HH:MM --.


      PREFIX
          String to be prepended to each line of log entry as it goes into
          your log file.  Default is the empty string.


      SUFFIX
          String to be appended to each line of log entry as it goes into
          your log file.  Default is the empty string.


      EDITOR
          The user's preferred editor (used by the -E command line flag and
          the ~e, ~E, and ~M escape sequences).  Default is
          /usr/local/bin/emacs.


      VISUAL
          The user's preferred visual editor (used by -V, ~v, and ~V).
          Default is /usr/local/bin/emacs.


      PAGER
          The user's preferred pager (used by -P, ~p, and ~P).  Default is
          /usr/local/bin/less.


      LINES
          The number of lines on the current display.  Used to determine
          when the PAGER needs to be invoked. Default is 24.


      CRYPTCMD
          The encryption command to be used.  If you do not wish to encrypt
          your log files, set this to null.  Default is /bin/crypt (the
          standard UNIX crypt command is not in the least secure, but does



                                    - 2 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



          provide protection from casual browsing).


      KEYVAL
          The key to be used with CRYPTCMD.  Default is pl<yr><mn>od.


      PROMPT
          Setting this variable to true (non-zero) causes PLOD to prompt the
          user for their encryption key rather than using KEYVAL.  This is
          equivalent to using the -s flag on the command line.  Default is
          false (zero).


      LOGDIR
          Where log files are placed.  Default is $HOME/.logdir.


      LOGFILE
          The name of the current log file.  LOGDIR will be prepended to
          this value if LOGFILE is not an absolute path.  Default is
          <yr><mn>.


      HOME
          The user's home directory.  Default taken from user's password
          entry.


      PLODRC
          The name of the user's startup file.  Can also be set with the -f
          command line switch.  Obviously, there isn't a lot of point in
          trying to set this in your .plodrc file.  HOME will be prepended
          to this value of PLODRC is not an absolute path.  Default is
          .plodrc.


      BACKUP
          The current LOGFILE is copied to BACKUP as the program begins
          execution.  If, when the program terminates, the LOGFILE is gone
          or zero-length, then it is replaced the the BACKUP copy and the
          current log entry is dumped to DEADLOG.  Setting BACKUP to null
          disables this feature.  The value of HOME is prepended if BACKUP
          is not an absolute path.  Default is .plod<pid>.bak.


      DEADLOG
          Where interrupted log entries are placed.  HOME will be prepended
          to this value if DEADLOG is not an absolute path.  Default is
          dead.log.




                                    - 3 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



      TMPFILE
          Scratch file used throughout execution of program.  Default is
          /tmp/plodtmp<pid>.



 COMMANDS
      Many tilde escape sequences are supported under PLOD's interactive
      mode.  Users may also define their own escape sequences in PLOD's
      initialization file (see CUSTOMIZATION below).  Currently defined
      sequences are:

      ~h, ~?  Show a list of all escape sequences with a short usage
              message.


      ~= var[, ...]
              Display the current value of one or more variables.

      ~e      Edit the current buffer with $EDITOR.


      ~v      Edit the current buffer with $VISUAL.


      ~p      Display the contents of the current buffer (using $PAGER if
              necessary).


      ~V [ logfile [ key ]]
              Call $VISUAL on the current log file, or on some other log
              file as specified.  An additional encryption key may also be
              supplied.


      ~E, ~l [ logfile [ key ]]
              Similar to ~E except that $EDITOR is used.


      ~P, ~L [ logfile [ key ]]
              Same as ~E and ~V except that $PAGER is invoked.


      ~q      Quit PLOD, saving contents of buffer into $DEADLOG.


      ~x      Quit without attempting to save buffer.







                                    - 4 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



      ~d      Append contents of $DEADLOG to current buffer.


      ~r somefile
              Append contents of file to current buffer.


      ~a somefile
              Append contents of current buffer to file.


      ~w somefile
              Overwrite file with contents of current buffer.


      ~X Perl-code
              Execute a line of Perl code.


      ~M      Invoke $EDITOR and execute resulting file as Perl code.  Each
              successive invocation of this escape will edit the previously
              executed Perl code so as to make it easier to go back and
              correct small errors.


      ~! command
              Execute a command in the shell and return.


      ~> command
              Append the output of a command to the current buffer.


      ~| command
              Pipe the current buffer through a command and replace the
              buffer with the resulting output.



 CUSTOMIZATION
      Like most UNIX utilities, PLOD has an initialization file, the
      .plodrc, which is read at startup.  Unlike most UNIX utilities, this
      file is interpreted as Perl code.  Thus, if you wished to assign a new
      value to a customization variable you would use the syntax

           $LOGDIR = "$HOME/mylogs";

      The location of the user startup file may changed with the -f command
      line switch or by setting the PLODRC environment variable.

      PLOD also looks for a system-wide customization file, /etc/plodrc.



                                    - 5 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



      The order of evaluation is: hard coded defaults in PLOD, then the
      /etc/plodrc file, then the user's environment, and finally the user's
      PLODRC file.

      Beyond simple variable customization, the PLODRC file can be used as
      an automatic pre-execution block and to define subroutines that will
      be used during the execution of the program.  For example, PLOD will
      attempt to execute user-defined &on_exit() or &on_error() routines (if
      they are defined) when the program terminates, depending upon whether
      the program exits normally or abnormally.

      Another application of this feature is to change the encryption scheme
      used by PLOD to use some alternate (more secure) encryption mechanism.
      Encryption and decryption in PLOD are done via &encrypt() and
      &decrypt() routines.  Both routines accept the same three arguments:
      a key value, an input file (either encrypted or decrypted depending
      upon which routine is being called), and an output file to place the
      result into.  The routines must return non-zero upon success and zero
      on failure, and should prompt the user for an encryption key if PROMPT
      is set.  As an example, here are the default &encrypt() and &decrypt()
      routines from the PLOD source:

           sub encrypt {
              local($key, $inputfl, $outputfl) = @_;
              local($safekey, $safeinp, $safeout);

              unlink($outputfl);

              if ($PROMPT) {   # Prompt for $KEYVAL if $PROMPT has been set
                 print "File is $file.0;
                 print "Please enter encryption key: ";
                 system 'stty', '-echo';
                 chop($key = <STDIN>);
                 system 'stty', 'echo';
                 print "0;
              }

              ($safekey = $key) =~ s/(W)/\$1/g;
              ($safeinp = $inputfl) =~ s/(W)/\$1/g;
              ($safeout = $outputfl) =~ s/(W)/\$1/g;
              !(system("$CRYPTCMD $safekey < $safeinp >$safeout") >> 8);
           }

           sub decrypt {
              local($key, $inputfl, $outputfl) = @_;
              local($safekey, $safeinp, $safeout);

              unlink($outputfl);

              if ($PROMPT) {   # Prompt for $KEYVAL if $PROMPT has been set
                 print "File is $file.0;



                                    - 6 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



                 print "Please enter encryption key: ";
                 system 'stty', '-echo';
                 chop($key = <STDIN>);
                 system 'stty', 'echo';
                 print "0;
              }

              ($safekey = $key) =~ s/(W)/\$1/g;
              ($safeinp = $inputfl) =~ s/(W)/\$1/g;
              ($safeout = $outputfl) =~ s/(W)/\$1/g;
              !(system("$CRYPTCMD $safekey < $safeinp >$safeout") >> 8);
           }

      Note that any possible meta characters in the key or in filenames are
      protected from the shell with backslashes before they are passed to
      system().  An &encrypt() or &decrypt() routine defined in the PLODRC
      will supercede the default definitions in the PLOD source.

      It is also possible for the user to create their own tilde escapes.
      First, create a subroutine which performs the desired function.  Then
      assign the type glob which references that function to global array
      %funcs indexed by the character of the escape sequence.  Any arguments
      that the user enters after the tilde escape will be passed into the
      function as a single string in @_.  The list @lines contains the
      current buffer.

      As an example, here is the append to file function (~a) from the PLOD
      source:

           sub appendfl {
              local($file) = @_;
              if (!open(OUTP, ">> $file")) {
                 warn "*** Could not append to file $file\n";
                 return;
              }
              print OUTP @lines;
              close(OUTP);
              print "Wrote ", scalar(@lines), " lines to file $file\n";
              print "(continue composing note)\n";
           }
           $appendfl = "file\t\tAppend contents of buffer to file";
           $funcs{'a'} = *appendfl;

      The scalar variable $appendfl is used by PLOD's help function (~h or
      ~?) to provide a descriptive message about the escape sequence.  As a
      further example, here is PLOD's help function

           sub helpuser {
              local($safename);
              $long = (scalar(keys %funcs) >= $LINES) && open(TMP, ">$TMPFILE");
              for (sort keys %funcs) {



                                    - 7 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



                 *info = $funcs{$_};
                 if ($long) {
                    print TMP "~$_ $info0;
                 }
                 else { print "~$_ $info0; }
              }
              if ($long) {
                 close(TMP);
                 ($safename = $TMPFILE) =~ s/(W)/\$1/g;
                 system("$PAGER $safename");
                 unlink $TMPFILE;
              }
           }
           $helpuser = "Print this message";
           $funcs{'h'} = *helpuser;
           $funcs{'?'} = *helpuser;

      Note the use of various customization variables as well as the
      assignment of the type glob to two different indices of the %funcs
      array.  Note also that again we protect any meta characters from the
      shell.

      Note that it is considered good form to return() from user defined
      subroutines rather than terminating PLOD prematurely.  If you must
      abort execution from within a routine, it is recommended that you call
      &PLODNormExit() or &PLODBadExit() so that you get both the BACKUP
      mechanism and the appropriate &on_exit() or &on_error() call.


 FILES
      $HOME/.plodrc           Default location for users' personal
                              initialization files


      /etc/plodrc             System-wide initialization file


      Various other customizable file locations.


 SEE ALSO
      perl(1)


 AUTHORS
      The original idea for PLOD comes from Bill Mendyka (mendyka@dg-
      rtp.dg.com).

      The current Perl implementation was developed by Hal Pomeranz
      (pomeranz@aqm.com).




                                    - 8 -      Formatted:  November 21, 2019






 PLOD(1)                            PLOD                             PLOD(1)
                               2 February 1993



      An Emacs mode for PLOD was developed by Paul Foley (paul@ascent.com),
      and another by Paul Hudson (paulh@harlequin.com).

      Additional improvements have been suggested/developed by: Bobby
      Billingsley (bobby@dc.dk), David W Crabb
      (crabb@phoenix.Princeton.EDU), Michel Dignard
      (dignard@ERE.UMontreal.CA), John Ellis (ellis@rtsg.mot.com), Bob
      Gibson (rjg@sco.COM), Mike Lachowski (mlachow@erenj.com), Eric
      Prestemon (ecprest@pocorvares.er.usgs.GOV), Erik E. Rantapaa
      (rantapaa@math.umn.edu), Scot Schneebeli (sls@tct.com), James Tizard
      (james@ringo.ssn.flinders.edu.au), and G. Paul Ziemba
      (paul@alantec.com).


 BUGS
      Any bug reports or suggestions for improvement should be submitted to
      Hal Pomeranz via email at pomeranz@aqm.com.





































                                    - 9 -      Formatted:  November 21, 2019