Update comments for new URL of Simon Taylor's GPO Clock Systems site

Add a usage message and trap various usage errors

clunk.8: Fix mandoc(1) lint errors.

README update.

clunk.service: Set Restart=on-failure.

This is recommended in systemd.service(5), and seems appropriate.
Most ways that clunk might fail are unlikely to be helped by
restarting it, but it's probably worth a try.

clunk.service: Support for some configuration through EnvironmentFile.

The default is still to use ClunkPi.

clunk.service: Don't hard-code the location of /var/lib.

systemd provides the "%S" specifier to refer to the parent of the
StateDirectory, so use that.

clunk.service: stop running clunk as root.

A combination of DynamicUser, SupplementaryGroups, an StateDirectory
allows it to have close to the minimum necessary privilege.

Switch back to calling clock_gettime unconditionally at start-up.

This is necessary in the case where the state file is empty and "-s"
is not used, and putting in the necessary conditions was getting too
complicated.

Add a CONFORMING TO section to clunk(8).

Add a systemd unit file.

Some documentation, in the form of a man page.

Add rough support for select libgpiod lines by number.

Build with libgpiod by default.

Crude sysfs-compatible output mode.

For pre-libgpiod systems.

Change option to request use of libgpiod to -G.

General plan: GPIO selection options are capital letters; other
options lower-case.

Control libgpiod code with #ifdef.

That way I can build on older Linux systems.

When recording dial time, write "12" instead of "0" for the hour.

12-hour clocks are generally thought of a running from 1 to 12, not
from 0 to 11.

Slightly more robust state string parsing.

Check the return value of snprintf().

I know it can't overflow, but this explains to GCC that I know.

Base the fallback timeout on how long we were expecting to sleep.

That way, if we were planning to sleep for a second we won't wait 31 s
before discovering that the clock's been set back.

Comment correction: refer to Clock No. 36 in present tense.

They still exist, albeit probably not in BT service.

Adjust pulsewidth and gapwidth.

Since pulsewidth is the length of the sleep in pulse(), it's
guaranteed that the actual pulse will be longer than this, so we can
safely set it to the minimum allowed, for minimum power consumption.

On the other hand, gapwidth should be raised slightly since a real
Clock No. 36 could would leave at least 500 ms between pulses (in
"advance" mode with a 500 ms pulse width).

Simplify code to clear pending SIGALRM.

A simple sigtimedwait() with a timeout of zero will do.  No need to
muck about with sigpending().

Don't call clock_getting unnecessarily at startup.

If the use has specified -s or -f, we don't need to initialise our
idea of the displayed time from CLOCK_REALTIME.

Remove a debugging printf.

Actually use the libgpiod output routine when asked.

Enforce a minimum "low" time for the output.

By sleeping for 250 ms after each pulse, we ensure that even if
CLOCK_REALTIME is suddenly put forward by 29.7 seconds we won't start
a new pulse before the dial has recovered from the last one.

Take advantage of sigtimedwait().

This saves the need for two separate timers, since the sigtimedwait()
timeout can serve the purpose of the fallback timer.

Only one pending signal might need clearing.

Don't depend on the field order of struct timespec.

POSIX merely requires that tv_sec and tv_nsec be present, so
initialisers need to name them explicitly.

Use two timers and sigwait rather than looking for EINTR.

The latter had a race condition whereby if the signal from the
fallback timer was delivered before the call to clock_nanosleep(), it
would be lost.  This was a fundamental problem with using asynchronous
signals, and switching to sigwait(), which can wait for blocked signals,
should solve it.

Add support for operating GPIO lines through libgpiod.

Untested, since the Raspberry Pi at my disposal doesn't yet have
libgpiod.

Use snprintf() in place of sprintf().

It shouldn't be necessary, but it seems polite.

Fix need_advance so it can't run off the end.

Fix init_statefile to not use optarg.

I failed to update it to use a local variable when I moved it out of
init().

Note which issue of B 5301 we're referencing.

Experimental use of structure literals.

Error handling for sigset functions.

Yes, they are allowed to return errors.  Even sigemptyset().

Utterly minimal Makefile.

Linux puts timer_* in -lrt, so we need to use that.

Make the fallback timer work.

It has a null signal handler, which has the side-effect of causing
clock_nanosleep to return EINTR.

Correct error handling for clock_nanosleep().

It apparently returns its errors rather than setting errno.

Remove a spurious space.

Create a timer to catch CLOCK_REALTIME going backwards.

Not used yet: I've spotted a couple of other problems to fix first.

Block SIGINT and SIGTERM while emitting a pulse.

That should ensure that we emit a full pulse and don't either truncate
it or leave the GPIO line high because of those signals.  SIGTERM will
catch a normal shutdown by systemd etc, SIGINT the manual killing of a
foreground process.

With "-s" specified, cope with empty or missing state file.

Implement reading from state file.

Record the current time displayed on the dial to a file.

This would allow for recovering from a power failure automatically, if
clunk bothered reading the file.

Better references in comments.

Adjust maxadvance doc to match 1 s advance rate.

Comment on pulse width and adjust advance rate.

Both based on the spec for Post Office clock 26 mark 6.  This
specifies the pulse width (200-500 ms) and the advance rate (one pulse
per second).

Factor out code to raise and lower output line from pulse().

The timing code in pulse is slightly twiddly and will probably be the
same for all output implementations.

Make the boundary between ADVANCE and STOP variable at compile time.

Add an option to specify the current displayed time at startup.

Start keeping track of what time we think the clock is displaying.

Call tzset() explicitly at startup.

It's required in portable code before invoking localtime_r().

Make the "pulse" have non-zero width.

Since I think most impulse clocks advance on the trailing edge of the
pulse, this requires subtracting the pulse width from the wake-up
time.

Minimal beginnings of an impulse clock driver.

Currently says "tick!" every 30 seconds.