aboutsummaryrefslogtreecommitdiffstats
path: root/pseudolog.1
blob: f11751fa88e91a656434ec1576370d000628d386 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
.\" 
.\" 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"
.SH SYNOPSIS
.B pseudolog \-l
.RB [ \-Pv ]
[
.B \-E
.I timeformat
]
.RI [ SPECIFICATIONS ]
.PP
.B pseudolog
.RB [ \-UPv ]
[
.B \-E
.I timeformat
]
[
.B \-F
.I format
]
.PP
.B pseudolog \-h
.PP
.B pseudolog \-D
.RB [ \-Pv ]
[
.B \-E
.I timeformat
]
.RI [ SPECIFICATIONS ]
.RI [ SPECIFICATIONS ]
.SH DESCRIPTION
The
.I pseudolog
utility displays, creates, or deletes log entries associated with the
.I 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
.IR specifications ,
and are detailed in the
.B SPECIFICATIONS
section below.

The following other options are supported:

.TP 8
.B \-h
Print a usage message and exit.
.TP 8
.B \-D
Delete rows selected by the query.  This is not reversible.
.TP 8
.BI \-E \ timeformat
Specify a format string (for
.I strptime(3)
or
.I strftime(3)
to use) for displaying or interpreting time stamps.  The same format
is used both for parsing and displaying stamps.
.TP 8
.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
a
.I printf(3)
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.
.TP 8
.B \-l
Create a log entry.  This option is mutually exclusive with the
.B \-F
option, or with any relative specifications (see below).
.TP 8
.BI \-P \ path
Specify that
.I path
should be used as the
.B PSEUDO_PREFIX
value, overriding any environment setting.
.TP 8
.B \-U
Restrict query output to unique rows.  Rows will have members defined by
the
.B \-F
(format) option.  If all members are the same between two rows, only one
is displayed.  Applies only to queries.
.TP 8
.B \-v
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.

.SH 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
.B =
operator).

.TP 8
.B >
Greater than; true if the related field is greater than the provided value.
.TP 8
.B <
Less than; true if the related field is less than the provided value.
.TP 8
.B &
Bitwise and; true if the related field, bitwise-and the provided value,
is non-zero.  (This is useful primarily for permissions or modes.)
.TP 8
.B =
Equal to.  (This is a no-op, as of this writing.)
.TP 8
.B !
Not equal to.
.TP 8
.B %
Similar to
.BR ~ .
This is valid only on text fields, and is equivalent to
the SQL
.B LIKE
operator, with 
.B %
patterns on the ends; it performs an unanchored, case-insensitive match.
.TP 8
.B ~
Similar to 
.BR % .
This is valid only on text fields, and is equivalent
to the SQL
.B LIKE
operator, but performs an anchored match.  The match is
case-insensitive.  The specifier
.B ~%foo%
is equivalent to the specifier
.BR %foo .
.TP 8
.B ^
Unlike.  This is the inverse of ~; it specifies 
.BR NOT\ LIKE .
.TP 8
.B \\
Escape the string.  This is useful if you want to have one of the
other modifiers at the beginning of the string.

.PP
Only
.BR = and \\
modifiers may be used in conjunction with the
.B \-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
.B 0
indicates an octal value, and a leading
.B 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.

.TP 8
.B a
Access mode.  This is an access mode specified in the form used by
.IR fopen(3) ,
such as "r+" to indicate read/write access.  Note that specifying
.B \&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
.B x
may be specified to indicate execute access.
.TP 8
.B c
Client ID (the PID of a client).
.TP 8
.B d
Device number (from a stat buffer).
.TP 8
.B f
File descriptor.  In some cases, messages have an associated file descriptor
identified.
.TP 8
.B g
GID.  The group ID associated with an entry.
.TP 8
.B G
Tag.  This is a text field.  In log entries created by
.IR pseudo ,
this field holds the value that the environment variable
.B PSEUDO_TAG
had in the client's environment.
.TP 8
.B i
Inode number (from a stat buffer).
.TP 8
.TP 8
.B 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.
.B m
Permissions.  These can be entered as an octal value or as a symbolic
mode string, similar to the output of
.I ls(1)
.BR -l.
The file type component is ignored.
.TP 8
.B M
Mode.  This can be entered as an octal value or as a symbolic mode
string, similar to the output of
.I ls(1)
.BR -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
.B m
or
.B t
specifiers.
.TP 8
.B o
Operation.  This is the name of the file system operation
(e.g., "open" or "rename").
.TP 8
.B 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.
.TP 8
.B p
File path.  This is a text field.
.TP 8
.B r
Result.  This is the
.I 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
.I pseudo
database.
.TP 8
.B R
Program.  This is the program name (as retrieved by glibc's
.I program_invocation_name
variable), which has the full path if and only if the program
was invoked by full path name.
.TP 8
.B s
Timestamp.  The format of this field is controlled by the
.B \-E
format string, which is used with
.I strftime(3)
when displaying entries, or with
.I 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.
.TP 8
.B S
Severity.  Log messages can have a severity, with the default for file
operations being "info".
.B t
File type.  This corresponds to the first letter of a mode string, or 
the values accepted by the
.B \-type
option to
.IR find(1) .
This is compared only against the file type bits of a mode.
.TP 8
.B 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.
.TP 8
.B u
UID.  The user ID associated with an entry.
.TP 8
.B 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).

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

.TP 8
.B pseudolog -m '&020' -t d
Report on all directories which are group-writeable.
.TP 8
.B pseudolog -m 755 -t f
Report on all plain files which have the mode rwxr-xr-x.
.TP 8
.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
current
date.
.TP 8
.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.
.TP 8
.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.
.TP 8
.B pseudolog -D -r succeed -F '%p' -O p
Display all paths for which operations succeeded, sorted by path value.

.SH ENVIRONMENT
The only environment variable supported by
.I pseudolog
is:
.TP 8
.B PSEUDO_PREFIX
If set, the variable
.B PSEUDO_PREFIX
is used to determine the path to use to find the
.I logs.db
database file, in
.BR PSEUDO_PREFIX /var/pseudo.

.SH 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
.I logs.db
file.

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

.SH SEE ALSO
pseudo(1), sqlite3(1)