Provided by: pseudo_1.9.0+git20230301+ec6151a2b057-1_amd64 bug

NAME

       pseudolog - pseudo log parser

SYNOPSIS

       pseudolog -l [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS]

       pseudolog [-UPv] [ -E timeformat ] [ -F format ] [ -x flags ]

       pseudolog -h

       pseudolog -D [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS] [SPECIFICATIONS]

DESCRIPTION

       The pseudolog utility displays, creates, or deletes log entries associated with the pseudo
       daemon.  Creation of log entries is  useful  only  to  create  timestamps  or  notes;  for
       instance,  you  could  create  a log entry before beginning a process, so there would be a
       timestamp for the beginning of that process.  There are a number of special  options  used
       to match or create the components of a log entry; these are called specifications, and are
       detailed in the SPECIFICATIONS section below.

       The following other options are supported:

       -h      Print a usage message and exit.

       -D      Delete rows selected by the query.  This is not reversible.

       -E timeformat
               Specify a format string (for strptime(3) or strftime(3) to use) for displaying  or
               interpreting time stamps.  The same format is used both for parsing and displaying
               stamps.

       -F format
               Specifies a format string for displaying log entries.  This format cannot be  used
               to  create  log  entries, only for display.  The format string is a printf(3) type
               format string, with format specifiers  matching  the  option  characters  used  in
               specifications  (see  SPECIFICATIONS).   There  are  some  limitations  on allowed
               formats, and  misuse  of  this  feature  could  cause  interesting  or  surprising
               failures.

       -l      Create a log entry.  This option is mutually exclusive with the -F option, or with
               any relative specifications (see below).

       -P path Specify that path should be  used  as  the  PSEUDO_PREFIX  value,  overriding  any
               environment setting.

       -U      Restrict  query  output  to unique rows.  Rows will have members defined by the -F
               (format) option.  If all members are the  same  between  two  rows,  only  one  is
               displayed.  Applies only to queries.

       -v      Increase  verbosity  (debug  level).   Not  useful  except  when debugging pseudo.
               Deprecated; use -x.

       -xflags Specify debugging flags of interest. Not useful except when debugging pseudo.

               Other option characters are defined as specifications, and all  of  those  require
               arguments to specify their values.

SPECIFICATIONS

       The various components of a log entry can be specified, either as command-line options, or
       as format specifiers.  In either case, the same character is used for a given component of
       a  log  entry.   When querying values, one of the following prefixes may be prepended to a
       value; otherwise, the value is used for a literal match (an SQL = operator).

       >       Greater than; true if the related field is greater than the provided value.

       <       Less than; true if the related field is less than the provided value.

       &       Bitwise and; true if the related field, bitwise-and the provided  value,  is  non-
               zero.  (This is useful primarily for permissions or modes.)

       =       Equal to.  (This is a no-op, as of this writing.)

       !       Not equal to.

       %       Similar  to  ~.   This  is valid only on text fields, and is equivalent to the SQL
               LIKE operator, with % patterns on the  ends;  it  performs  an  unanchored,  case-
               insensitive match.

       ~       Similar  to  %.   This  is valid only on text fields, and is equivalent to the SQL
               LIKE operator, but performs an anchored match.   The  match  is  case-insensitive.
               The specifier ~%foo% is equivalent to the specifier %foo.

       ^       Unlike.  This is the inverse of ~; it specifies NOT LIKE.

               Escape  the string.  This is useful if you want to have one of the other modifiers
               at the beginning of the string.

       Only =and.ft R modifiers may be used in conjunction with the -l option.

       The following characters correspond to specific  fields  in  a  log  entry.   In  general,
       numeric  values  are  parsed in the standard C idiom (where a leading 0 indicates an octal
       value, and a leading 0x indicates a hexadecimal value, and any other number  is  decimal).
       A few fields are parsed or displayed in other ways, as detailed in their entries.

       a       Access  mode.  This is an access mode specified in the form used by fopen(3), such
               as "r+" to indicate read/write access.  Note that specifying a as an  access  mode
               will  include  non-append  writes,  as the "a" mode implies write and append both.
               This feature is slightly experimental and may not correctly  identify  the  access
               type of every access.  The string x may be specified to indicate execute access.

       c       Client ID (the PID of a client).

       d       Device number (from a stat buffer).

       f       File  descriptor.   In  some  cases,  messages  have an associated file descriptor
               identified.

       g       GID.  The group ID associated with an entry.

       G       Tag.  This is a text field.  In log entries created by pseudo,  this  field  holds
               the   value   that  the  environment  variable  PSEUDO_TAG  had  in  the  client's
               environment.

       i       Inode number (from a stat buffer).

       I       ID.   This  is  the  database  row  number.   Normally  these  are   assigned   as
               monotonically  increasing values as rows are inserted, making them a more reliable
               sorting mechanism than timestamps.  The default ordering is by ID.  m Permissions.
               These  can  be  entered as an octal value or as a symbolic mode string, similar to
               the output of ls(1) -l.  The file type component is ignored.

       M       Mode.  This can be entered as an octal value or as a symbolic mode string, similar
               to  the output of ls(1) -l.  This is tested against the whole file mode, including
               both the type and permissions bits.  In general, it is more useful to use the m or
               t specifiers.

       o       Operation.   This  is  the  name  of  the  file  system operation (e.g., "open" or
               "rename").

       O       Order.  This takes another specification character as the field on which to  order
               results.  A '<' implies a descending order sort, a '>' or no modifier specifies an
               ascending order sort.  By default, records are sorted by ID.

       p       File path.  This is a text field.

       r       Result.  This is the pseudo result code, most often  "fail"  or  "succeed".   Note
               that  "fail"  doesn't mean that an underlying operation failed; for instance, if a
               "stat" operation fails, it usually means that there was no  entry  in  the  pseudo
               database.

       R       Program.     This    is    the    program    name   (as   retrieved   by   glibc's
               program_invocation_name variable), which has the full path  if  and  only  if  the
               program was invoked by full path name.

       s       Timestamp.   The format of this field is controlled by the -E format string, which
               is used with  strftime(3)  when  displaying  entries,  or  with  strptime(3)  when
               interpreting  command  line  values.  There is a small selection of common default
               time formats understood by the parser.  Time fields not specified default  to  the
               current  time.   Note  that  specifying a time stamp when creating a log entry may
               yield confusing results.

       S       Severity.  Log messages can have a severity, with the default for file  operations
               being  "info".   t  File  type.   This  corresponds  to the first letter of a mode
               string, or the values accepted by the -type option to find(1).  This  is  compared
               only against the file type bits of a mode.

       T       Text.  This is an optional field available for user use when creating log entries,
               or to hold the text of an error message when  an  error  is  logged.   It  is,  of
               course, a text field.

       u       UID.  The user ID associated with an entry.

       y       Type.   This  is  usually  "op"  for  operations,  or "ping" for the ping messages
               clients send to confirm server availability.  Other types should rarely occur, but
               include  "ack" and "nak" for server responses (which are never logged), and "halt"
               for shutdown messages (currently not logged).

EXAMPLES

       The following examples illustrate some of the likely usage patterns for pseudolog.

       pseudolog -m '&020' -t d
               Report on all directories which are group-writeable.

       pseudolog -m 755 -t f
               Report on all plain files which have the mode rwxr-xr-x.

       pseudolog -s '>03:19:00' -s '<03:20:00'
               Report on all entries created after 03:19:00 and before 03:20:00  on  the  current
               date.

       pseudolog -p '~/usr/bin/%' -F '%-8o %p'
               Report on every entry with a path beginning with the string '/usr/bin', displaying
               the operation name (in a space-padded field of  eight  characters,  left-adjusted)
               followed by the path.

       pseudolog -l -T 'stamp test'
               Create an entry with all fields zero or blank, except for the text field, which is
               set to the text "stamp test", and the timestamp, which is set to the current time.

       pseudolog -D -r succeed -F '%p' -O p
               Display all paths for which operations succeeded, sorted by path value.

ENVIRONMENT

       The only environment variable supported by pseudolog is:

       PSEUDO_PREFIX
               If set, the variable PSEUDO_PREFIX is used to determine the path to  use  to  find
               the logs.db database file, in PSEUDO_PREFIX/var/pseudo.

BUGS

       The  user might think our intent is to replace all of SQL.  It's not.  If the options here
       aren't enough, rather than adding more options to this already fairly  elaborate  program,
       just do raw SQL queries on the logs.db file.

       The  formatting  options  are  handled  by  converting them into printf(3) format strings,
       without much checking.  As a result, it is possible for a malformed format string to cause
       printf() to explode unexpectedly.

SEE ALSO

       pseudo(1), sqlite3(1)

                                  pseudo - pretending to be root                     pseudolog(1)