xenial (1) pseudolog.1.gz

Provided by: pseudo_1.7.4-2_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)