1pseudolog(1) General Commands Manual pseudolog(1)
2
6 pseudolog - pseudo log parser
7
9 pseudolog -l [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS]
10 pseudolog [-UPv] [ -E timeformat ] [ -F format ] [ -x flags ]
12 pseudolog -h
14 pseudolog -D [-Pv] [ -E timeformat ] [ -x flags ] [SPECIFICATIONS]
16 [SPECIFICATIONS]
17
19 The pseudolog utility displays, creates, or deletes log entries associ‐
20 ated with the pseudo daemon. Creation of log entries is useful only to
21 create timestamps or notes; for instance, you could create a log entry
22 before beginning a process, so there would be a timestamp for the
23 beginning of that process. There are a number of special options used
24 to match or create the components of a log entry; these are called
25 specifications, and are detailed in the SPECIFICATIONS section below.
26 The following other options are supported:
28 -h Print a usage message and exit.
31 -D Delete rows selected by the query. This is not reversible.
33 -E timeformat
35 Specify a format string (for strptime(3) or strftime(3) to use)
36 for displaying or interpreting time stamps. The same format is
37 used both for parsing and displaying stamps.
38 -F format
40 Specifies a format string for displaying log entries. This
41 format cannot be used to create log entries, only for display.
42 The format string is a printf(3) type format string, with for‐
43 mat specifiers matching the option characters used in specifi‐
44 cations (see SPECIFICATIONS). There are some limitations on
45 allowed formats, and misuse of this feature could cause inter‐
46 esting or surprising failures.
47 -l Create a log entry. This option is mutually exclusive with the
49 -F option, or with any relative specifications (see below).
50 -P path Specify that path should be used as the PSEUDO_PREFIX value,
52 overriding any environment setting.
53 -U Restrict query output to unique rows. Rows will have members
55 defined by the -F (format) option. If all members are the same
56 between two rows, only one is displayed. Applies only to
57 queries.
58 -v Increase verbosity (debug level). Not useful except when
60 debugging pseudo. Deprecated; use -x.
61 -xflags Specify debugging flags of interest. Not useful except when
63 debugging pseudo.
64 Other option characters are defined as specifications, and all
66 of those require arguments to specify their values.
67
70 The various components of a log entry can be specified, either as com‐
71 mand-line options, or as format specifiers. In either case, the same
72 character is used for a given component of a log entry. When querying
73 values, one of the following prefixes may be prepended to a value; oth‐
74 erwise, the value is used for a literal match (an SQL = operator).
75 > Greater than; true if the related field is greater than the
78 provided value.
79 < Less than; true if the related field is less than the provided
81 value.
82 & Bitwise and; true if the related field, bitwise-and the pro‐
84 vided value, is non-zero. (This is useful primarily for per‐
85 missions or modes.)
86 = Equal to. (This is a no-op, as of this writing.)
88 ! Not equal to.
90 % Similar to ~. This is valid only on text fields, and is equiv‐
92 alent to the SQL LIKE operator, with % patterns on the ends; it
93 performs an unanchored, case-insensitive match.
94 ~ Similar to %. This is valid only on text fields, and is equiv‐
96 alent to the SQL LIKE operator, but performs an anchored match.
97 The match is case-insensitive. The specifier ~%foo% is equiva‐
98 lent to the specifier %foo.
99 ^ Unlike. This is the inverse of ~; it specifies NOT LIKE.
101 Escape the string. This is useful if you want to have one of
103 the other modifiers at the beginning of the string.
104 Only =and.ft R modifiers may be used in conjunction with the -l option.
107 The following characters correspond to specific fields in a log entry.
109 In general, numeric values are parsed in the standard C idiom (where a
110 leading 0 indicates an octal value, and a leading 0x indicates a hexa‐
111 decimal value, and any other number is decimal). A few fields are
112 parsed or displayed in other ways, as detailed in their entries.
113 a Access mode. This is an access mode specified in the form used
116 by fopen(3), such as "r+" to indicate read/write access. Note
117 that specifying a as an access mode will include non-append
118 writes, as the "a" mode implies write and append both. This
119 feature is slightly experimental and may not correctly identify
120 the access type of every access. The string x may be specified
121 to indicate execute access.
122 c Client ID (the PID of a client).
124 d Device number (from a stat buffer).
126 f File descriptor. In some cases, messages have an associated
128 file descriptor identified.
129 g GID. The group ID associated with an entry.
131 G Tag. This is a text field. In log entries created by pseudo,
133 this field holds the value that the environment variable
134 PSEUDO_TAG had in the client's environment.
135 i Inode number (from a stat buffer).
137 I ID. This is the database row number. Normally these
140 are assigned as monotonically increasing values as rows
141 are inserted, making them a more reliable sorting mecha‐
142 nism than timestamps. The default ordering is by ID. m
143 Permissions. These can be entered as an octal value or
144 as a symbolic mode string, similar to the output of
145 ls(1) -l. The file type component is ignored.
146 M Mode. This can be entered as an octal value or as a
148 symbolic mode string, similar to the output of ls(1) -l.
149 This is tested against the whole file mode, including
150 both the type and permissions bits. In general, it is
151 more useful to use the m or t specifiers.
152 o Operation. This is the name of the file system opera‐
154 tion (e.g., "open" or "rename").
155 O Order. This takes another specification character as
157 the field on which to order results. A '<' implies a
158 descending order sort, a '>' or no modifier specifies an
159 ascending order sort. By default, records are sorted by
160 ID.
161 p File path. This is a text field.
163 r Result. This is the pseudo result code, most often
165 "fail" or "succeed". Note that "fail" doesn't mean that
166 an underlying operation failed; for instance, if a
167 "stat" operation fails, it usually means that there was
168 no entry in the pseudo database.
169 R Program. This is the program name (as retrieved by
171 glibc's program_invocation_name variable), which has the
172 full path if and only if the program was invoked by full
173 path name.
174 s Timestamp. The format of this field is controlled by
176 the -E format string, which is used with strftime(3)
177 when displaying entries, or with strptime(3) when inter‐
178 preting command line values. There is a small selection
179 of common default time formats understood by the parser.
180 Time fields not specified default to the current time.
181 Note that specifying a time stamp when creating a log
182 entry may yield confusing results.
183 S Severity. Log messages can have a severity, with the
185 default for file operations being "info". t File type.
186 This corresponds to the first letter of a mode string,
187 or the values accepted by the -type option to find(1).
188 This is compared only against the file type bits of a
189 mode.
190 T Text. This is an optional field available for user use
192 when creating log entries, or to hold the text of an
193 error message when an error is logged. It is, of
194 course, a text field.
195 u UID. The user ID associated with an entry.
197 y Type. This is usually "op" for operations, or "ping"
199 for the ping messages clients send to confirm server
200 availability. Other types should rarely occur, but
201 include "ack" and "nak" for server responses (which are
202 never logged), and "halt" for shutdown messages (cur‐
203 rently not logged).
204
207 The following examples illustrate some of the likely usage pat‐
208 terns for pseudolog.
209 pseudolog -m '&020' -t d
212 Report on all directories which are group-writeable.
213 pseudolog -m 755 -t f
215 Report on all plain files which have the mode rwxr-xr-x.
216 pseudolog -s '>03:19:00' -s '<03:20:00'
218 Report on all entries created after 03:19:00 and before
219 03:20:00 on the current date.
220 pseudolog -p '~/usr/bin/%' -F '%-8o %p'
222 Report on every entry with a path beginning with the
223 string '/usr/bin', displaying the operation name (in a
224 space-padded field of eight characters, left-adjusted)
225 followed by the path.
226 pseudolog -l -T 'stamp test'
228 Create an entry with all fields zero or blank, except
229 for the text field, which is set to the text "stamp
230 test", and the timestamp, which is set to the current
231 time.
232 pseudolog -D -r succeed -F '%p' -O p
234 Display all paths for which operations succeeded, sorted
235 by path value.
236
239 The only environment variable supported by pseudolog is:
240 PSEUDO_PREFIX
242 If set, the variable PSEUDO_PREFIX is used to determine
243 the path to use to find the logs.db database file, in
244 PSEUDO_PREFIX/var/pseudo.
245
248 The user might think our intent is to replace all of SQL. It's
249 not. If the options here aren't enough, rather than adding more
250 options to this already fairly elaborate program, just do raw
251 SQL queries on the logs.db file.
252 The formatting options are handled by converting them into
254 printf(3) format strings, without much checking. As a result,
255 it is possible for a malformed format string to cause printf()
256 to explode unexpectedly.
257
260 pseudo(1), sqlite3(1)
261 pseudo - pretending to be root pseudolog(1)