calendar_lockfiles
Attempt to lock the files given in the argument. To prevent
problems with network file locking this is done in an ad hoc fashion
by attempting to create a symbolic link to the file with the name
file.lockfile
. No other system level functions are used
for locking, i.e. the file can be accessed and modified by any
utility that does not use this mechanism. In particular, the user is not
prevented from editing the calendar file at the same time unless
calendar_edit
is used.
Three attempts are made to lock the file before giving up. If the module
zsh/zselect
is available, the times of the attempts are jittered so that
multiple instances of the calling function are unlikely to retry at the
same time.
The files locked are appended to the array lockfiles
, which should
be local to the caller.
If all files were successfully locked, status zero is returned, else status one.
This function may be used as a general file locking function, although this will only work if only this mechanism is used to lock files.
calendar_read
This is a backend used by various other functions to parse the
calendar file, which is passed as the only argument. The array
calendar_entries
is set to the list of events in the file; no
pruning is done except that ampersands are removed from the start of
the line. Each entry may contain multiple lines.
calendar_scandate
This is a generic function to parse dates and times that may be
used separately from the calendar system. The argument is a date
or time specification as described in
File and Date Formats. The parameter REPLY
is set to the number of seconds since the epoch corresponding to that date
or time. By default, the date and time may occur anywhere within the given
argument.
Returns status zero if the date and time were successfully parsed, else one.
Options:
-a
The date and time are anchored to the start of the argument; they will not be matched if there is preceding text.
-A
The date and time are anchored to both the start and end of the argument; they will not be matched if the is any other text in the argument.
-d
Enable additional debugging output.
-m
Minus. When -R
anchor_time is also given the relative time is
calculated backwards from anchor_time.
-r
The argument passed is to be parsed as a relative time.
-R
anchor_timeThe argument passed is to be parsed as a relative time. The time is relative to anchor_time, a time in seconds since the epoch, and the returned value is the absolute time corresponding to advancing anchor_time by the relative time given. This allows lengths of months to be correctly taken into account. If the final day does not exist in the given month, the last day of the final month is given. For example, if the anchor time is during 31st January 2007 and the relative time is 1 month, the final time is the same time of day during 28th February 2007.
-s
In addition to setting REPLY
, set REPLY2
to the remainder of
the argument after the date and time have been stripped. This is
empty if the option -A
was given.
-t
Allow a time with no date specification. The date is assumed to be today. The behaviour is unspecified if the iron tongue of midnight is tolling twelve.
calendar_show
The function used by default to display events. It accepts a start time and end time for events, both in epoch seconds, and an event description.
The event is always printed to standard output. If the command line editor is active (which will usually be the case) the command line will be redisplayed after the output.
If the parameter DISPLAY
is set and the start and end times are
the same (indicating a scheduled event), the function uses the
command xmessage
to display a window with the event details.