[Go to CFHT Home Page] Man Pages
Back to Software Index  BORDER=0Manpage Top Level
    ROLL(1) manual page Table of Contents

Name

roll, unroll - insert and extract lines to/from a circular file

Synopsis

roll [-L|-b|-F] [-v] [-S] [-s [-p [ filename ]

unroll [-v] [-h [-f [-t [-a [ filename ]

Description

roll will maintain a fixed size file filename that contains a circular queue of lines. This file has the property that each line read from stdin will replace the oldest line(s) currently in the file.

unroll will print each line from a file filename created with roll on its stdout.

Both programs process all the options given above. Any that do not make sense for the program are not used.

Options and Argument

-L
This option will cause roll to create a backwards roll file. This will result in a LIFO circular file and is the default. When a LIFO file is unrolled, the most recent line is output first, followed in reverse time sequence by earlier lines. The file created with this option will always have this attribute. If filename already exists, this option will do nothing.
-b
Same as -L.
-F
This option will cause roll to create a forwards roll file. This will result in a FIFO circular file instead of the default LIFO file. When a FIFO file is unrolled, the oldest line is output first, followed in increasing time sequence by later lines. The file created with this option will always have this attribute. If filename already exists, this option will do nothing.
-v
Verbose option. Various extra messages will be placed on stderr.
-S
This option used to allow roll to be run as another user if the executable file is suid to that user. It has been removed because we do not use this feature, and it was not implemented correctly, and for the wrong reasons. The option is silently accepted for compatability.
-s
If filename does not exist and roll is used, the file will be created so as to hold approximately size bytes before wrapping around. If size is not given, a default of 1048576 bytes (1M) is used.
-p " pipe"
Indicates that the next argument is the input file for roll to use. stdin will be re-opened to this file for reading. This is usually used with a session named pipe to which all programs log messages.
-h " hours"
This option will cause unroll to output lines from hours ago up through now. If none of the -h, -f, or -t options are given, a -h 6 is supplied. This option depends on the line format created by cfht_logv(3) . This option is incompatible with -f and -t.
-f " from"
This option will cause unroll to output only lines more recent than time from. If -f is given but -t is not, all lines in the file after from are output. See below for the format of from. This option depends on the line format created by cfht_logv(3) . This option is incompatible with -h.
-t " to"
This option will cause unroll to output only lines older than time to. If -t is given but -f is not, all lines in the file older than to are output. See below for the format of to. This option depends on the line format created by cfht_logv(3) . This option is incompatible with -h.
-a " acct"
This option prints only lines which have acct as their first word. For log files created by cfht_logv(3) calls, this word is the session account name.
-r
This option will force roll or unroll to be roll.
-u
This option will force roll or unroll to be unroll.
filename
This specifies the file name that roll is to write or unroll is to read. If filename is not given, the default is the normal session roll file, $cfhtdir/dev/conf/syslog.@.

Time Format

The dates and times accepted by the -f and -t options are relatively free format. There is some error checking, but the aim was to accept pretty much anything without bogging down in checking for February 30th. Time scanning begins with a default of the current time as the initial result. Any fields encountered in from or to are updated in the result. For example, noon will change the time to 12:00:00 but leave the date alone, PM will make sure the time is in the afternoon, and yesterday will change the date to yesterday’s date but leave the time alone.

The possible field values include the following. Any alphabetical value given can be abbreviated uniquely. Any combination of case can be used.

weekday
Sunday, etc., sets the date to the nearest earlier (including today) day of the week specified. On Wednesday, Wed is today, Tuesday is yesterday, and Th is 6 days ago.
today
sets the date to today’s date (probably it already was).
yesterday
sets the date to yesterday’s date.
now
sets the time to now (probably it already was).
midnight
sets the time to 00:00:00.
sunrise
sets the time to 06:00:00.
noon
sets the time to 12:00:00.
sunset
sets the time to 18:00:00.
AM
is ignored unless the hour is 12, in which case the hour is changed to 0.
PM
makes sure the hour is 12 or more.
hhmm
sets the time to hh:mm:00.
h
where h is not 4 digits long sets the time to h:00:00.
hh:mm
sets the time to hh:mm:00.
hh:mm:ss
sets the time to hh:mm:ss. Decimal seconds are ignored.
mm-dd-yy
sets the date to that given. If yy is not given, the current year is used. If yy is greater than 1900, it is assumed to be a full year specification. "/" can be used instead of "-".
dd-mmm-yy
where mmm is alphabetic sets the date to that given, with the same qualifications as for the mm-dd-yy form.
mmm
sets the month to that given (why bother? - just to fill out the case :-)

Examples

The normal roll startup at CFHT used to be
roll -S -p /tmp/pipes/syslog.np &
but now that roll detaches from the terminal, it can be started in the foreground, and it will become a daemon process as soon as the roll is set up (which can take a while if syslog.@ needs to be created.) It is also no longer necessary to create /tmp/pipes/syslog.np first. roll will do it if it doesn’t exist (including creating the special directory /tmp/pipes.) So the complete startup recommended for CFHT is now
CFHTLOGU=
CFHTLOGS=/tmp/pipes/syslog.np
export CFHTLOGU CFHTLOGS
/cfht/bin/roll -s 24000000 -p $CFHTLOGS
/cfht/bin/cfht_log reboot START @logging system started by $0@

Possible list requests include the following

unroll -h 1 - look at the past hour
unroll -t yes - look from beginning to this time yesterday
unroll -f @yes suns@ -t mid - look at yesterday evening
unroll -f mon -t tu - look from now Monday to now Tuesday
unroll -f 1AM -t 0800 - look from 01:00 to 08:00 today
unroll -f @10-31 mid@ -t @2/nov sunr@ - look from 00:00 31-Oct-?? to 06:00 02-Nov-??
unroll -h 2 -a mos - look at all mos lines for the last 2 hours

The following example will reverse the lines in a small (<1M) file:
roll -b file.@ <file; unroll file.@ >file.r; rm file.@

Diagnostics

Normal diagnostics include notification of creation, recoverable corrupt format, unrecoverable invalid format, default and minimum file size overrides, disallowed input characters (see below), line length exceeded for LIFO, another roll active on filename, and a usage statement when invoked with illegal arguments.

Verbose diagnostics include position of end-of-data mark, size of file, type of file (FIFO or LIFO), length and file offsets for each write(s), notification of wrapping past end of file, position of end-of-data mark and file size upon closing of roll file, re-opening of stdin, and notification that a signal was caught causing a closure of the roll file.

Warnings

Line lengths longer than 1024 will be flushed out to the roll file in multiple transactions. This will cause the backward LIFO file to have the line scrambled as the last part will be unrolled first, followed by the earlier parts. FIFO files will be in the correct order with long lines split.

The size option will result in a file that will hold size-n bytes, where n is currently 6.

The first line output from a FIFO file (by unroll) may not be a complete line.

Eight bit values are allowed with the exception of NULL(0x0) and (0xFF).

Bugs

Roll makes all time calculations in local-time instead of UTC. If you get unexpected results, make sure the TZ variable seen by unroll is set the same as for the programs which wrote to the log.

When the -h, -f, or -t options are used, a few extra lines may appear or some expected lines may not appear. This is because the time comparison is keyed off the (start) lines in the roll file. They are the only ones with time and date. To see everything in a LIFO file, use For a FIFO file, use

Table of Contents