|author||Peter Seebach <seebs@eee12.(none)>||2010-03-16 19:26:24 -0500|
|committer||Peter Seebach <seebs@eee12.(none)>||2010-03-16 19:26:24 -0500|
initial public release
Diffstat (limited to 'pseudolog.1')
1 files changed, 335 insertions, 0 deletions
diff --git a/pseudolog.1 b/pseudolog.1
new file mode 100644
@@ -0,0 +1,335 @@
+.\" pseudolog(1) man page
+.\" Copyright (c) 2010 Wind River Systems, Inc.
+.\" This program is free software; you can redistribute it and/or modify
+.\" it under the terms of the Lesser GNU General Public License version 2.1 as
+.\" published by the Free Software Foundation.
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\" See the Lesser GNU General Public License for more details.
+.\" You should have received a copy of the Lesser GNU General Public License
+.\" version 2.1 along with this program; if not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+.TH pseudolog 1 "pseudo - pretending to be root"
+.B pseudolog -l
+.RB [ \-Pv ]
+.RI [ SPECIFICATIONS ]
+.RB [ \-DPv ]
+.RI [ SPECIFICATIONS ]
+utility displays log entries created by the
+daemon, or creates log entries. 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
+.IR specifications ,
+and are detailed in the
+The following other options are supported:
+Restrict query output to distinct rows. Rows will have members defined by
+(format) option. If all members are the same between two rows, only one
+is displayed. Applies only to queries.
+.BI \-E \ timeformat
+Specify a format string (for
+to use) for displaying or interpreting time stamps. The same format
+is used both for parsing and displaying stamps.
+.BI \-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
+type format string, with format specifiers matching the option characters
+used in specifications (see
+.BR SPECIFICATIONS ).
+There are some limitations on allowed formats, and misuse of this feature
+could cause interesting or surprising failures.
+Create a log entry. This option is mutually exclusive with the
+option, or with any relative specifications (see below).
+.BI \-P \ path
+should be used as the
+value, overriding any environment setting.
+Increase verbosity (debug level). Not useful except when debugging pseudo.
+Other option characters are defined as specifications, and all of those
+require arguments to specify their values.
+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
+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.
+.BR ~ .
+This is valid only on text fields, and is equivalent to
+patterns on the ends; it performs an unanchored, case-insensitive match.
+.BR % .
+This is valid only on text fields, and is equivalent
+to the SQL
+operator, but performs an anchored match. The match is
+case-insensitive. The specifier
+is equivalent to the specifier
+.BR %foo .
+Unlike. This is the inverse of ~; it specifies
+.BR NOT\ LIKE .
+Escape the string. This is useful if you want to have one of the
+other modifiers at the beginning of the string.
+.BR = and \\
+modifiers may be used in conjunction with the
+The following characters correspond to specific fields in a log entry.
+In general, numeric values are parsed in the standard C idiom (where
+indicates an octal value, and a leading
+indicates a hexadecimal value, and any other number is decimal). A
+few fields are parsed or displayed in other ways, as detailed in their
+Client ID (the PID of a client).
+Device number (from a stat buffer).
+File descriptor. In some cases, messages have an associated file descriptor
+GID. The group ID associated with an entry.
+Tag. This is a text field. In log entries created by
+.IR pseudo ,
+this field holds the value that the environment variable
+had in the client's environment.
+Inode number (from a stat buffer).
+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.
+Permissions. These can be entered as an octal value or as a symbolic
+mode string, similar to the output of
+The file type component is ignored.
+Mode. This can be entered as an octal value or as a symbolic mode
+string, similar to the output of
+This is tested against the whole file mode, including both the type
+and permissions bits. In general, it is more useful to use the
+Operation. This is the name of the file system operation
+(e.g., "open" or "rename").
+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.
+File path. This is a text field.
+Result. This is the
+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
+Timestamp. The format of this field is controlled by the
+format string, which is used with
+when displaying entries, or with
+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.
+Severity. Log messages can have a severity, with the default for file
+operations being "info".
+File type. This corresponds to the first letter of a mode string, or
+the values accepted by the
+.IR find(1) .
+This is compared only against the file type bits of a mode.
+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.
+UID. The user ID associated with an entry.
+The following examples illustrate some of the likely usage patterns for
+.IR pseudolog .
+.B pseudolog -m '&020' -t d
+Report on all directories which are group-writeable.
+.B pseudolog -m 755 -t f
+Report on all plain files which have the mode rwxr-xr-x.
+.B 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
+.B 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.
+.B 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.
+.B pseudolog -D -r succeed -F '%p' -O p
+Display all paths for which operations succeeded, sorted by path value.
+The only environment variable supported by
+If set, the variable
+is used to determine the path to use to find the
+database file, in
+.BR PSEUDO_PREFIX /var/pseudo.
+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
+The formatting options are handled by converting them into
+format strings, without much checking. As a result, it
+is possible for a malformed format string to cause
+to explode unexpectedly.
+.SH SEE ALSO