build: Combine CFLAGS and DEBUG_CFLAGS.

We needed two sets of flags for gengetopt because the C code generated
by gengetopt would not compile cleanly with our rather strict set of
flags. With lopsub this is no longer necessary.

Moreover, it is considered good practice to not set CFLAGS at all but
to append the contents of this variable to the compile command. This
way the user may set the variable to override some of the options.

This commit gets rid of CFLAGS in favor of DSS_CFLAGS, which is just
the union of the CFLAGS and the DEBUG_CFLAGS variables we had before.

Implement --checksum.

It is considered good practice to run rsync with --checksum from time
to time. This patch implements the feature via the new --checksum
option.

The probabilistic approach was chosen so that dss does not need to
remember which snapshots were created with --checksum.

run: Improve error diagnostics for chdir(2) failure.

In run mode, if the destination directory does not exist, dss prints
"No such file or directory" and exits, without telling the user (a)
it was a failed chdir(2) call that caused the error, and (b) the name
of the directory. This patch adds an error message containing this
information.

Since there is only one caller of dss_chdir(), let's get rid
of this public function in file.c and call chdir() directly from
change_to_dest_dir() of dss.c.

run: Improve error message if dss is already running.

The current error message, "child terminated unexpectedly", is not
very comprehensive.

The most likely reason for the child to terminate is that it could not
obtain the semaphore lock because another dss process is running. This
commit adds a test to com_run() that check this condition in the
parent before the child process is born. This way, if another process
is holding the lock, we can fail with a nice error message that also
includes the pid of the process that holds the lock.

run: Fix exit status in case another dss process is running.

In daemon mode, we must acquire the semaphore lock in the child process
because the child does not inherit semaphore adjustments. Currently
the parent exits successfully after the fork, so the command appears
to succeed even if the child dies immediately because it was unable
to acquire the lock because another dss process is holding the lock.

This commit introduces a mechanism which enables the parent to tell
whether the child completed its setup successfully. We create a
pipe prior to calling fork(2), and let the child write to one end
of the pipe after setup is complete and just before it enters the
main select loop. The parent reads from the other end of the pipe
and exits once the read(2) call returns. If the child dies early,
read(2) returns zero, indicating failure.

build: Add target install and install-strip.

It has always been a bit clumsy to copy the executable and the
manual page to their proper locations by hand, so this commit adds
the two standard targets "install" and "install-strip" which install
both files.

The installation prefix defaults to /usr/local and can be set with
PREFIX. Moreover, there is DESTDIR which may be given to prepend
another directory (useful for for "staged installs", where the
installed files are not placed directly into their expected location
but are instead copied into a temporary location).

Convert dss to lopsub.

This commit ditches gengetopt for the command line and config file
parsers in favor of the lopsub library. Hence from now on, lopsub
must be installed in order to compile dss while gengetopt is no
longer needed.

The mutually exclusive gengetopt group options --create, --prune, --ls,
--run, --kill and --reload are replaced by lopsub subcommands. However,
the --reload and --kill options have been combined to the new "kill"
subcommand which allows to send arbitrary signals to a running dss
process.

Due to the conversion, the syntax of the dss command changes
slightly. For example,

dss --run

becomes

dss run

while

dss -Rdc foo

needs to be spelled as

dss -c foo -- run -d

so that -d is regarded as an option to the "run" subcommand rather
than an option to dss.

With lopsub each subcommand has its own command line and config file
parser. Options to subcommands can be added to the configuration file
like this:

[run]
daemon
logfile=/var/log/dss.log

As for the implementation, the bulk of the changes is the conversion
of dss.ggo to the new dss.suite. The necessary adjustments to the
code are relatively simple. In particular, only dss.c needs to be
changed while all other .c files don't require any modifications.

The examples in INSTALL are adjusted to the new syntax. The commit also
drops support for Mac OS and Solaris, since lopsub is not supported
on these platforms yet.

ipc: Combine mutex_lock() and lock_dss().

The former function is only called by the latter, and both are short,
so let's combine them.

ipc: Prefer key_t over int for System V IPC keys.

get_key() calls ftok(3), which returns a key_t value. key_t is also
the type which semget(2), the only function which receives the key via
mutex_get(), expects. It's stupid to convert the key_t from ftok(3)
into an int, only to convert it back to key_t later.

This patch changes ipc.c to use key_t everywhere. However, in
mutex_get() we print a log message containing the value of the key,
so the format string must be adjusted accordingly. Unfortunately,
on Linux, key_t is the same as int while on FreeBSD and NetBSD it is
defined as long. To avoid a warning from the compiler we use "%lx"
in the format string and cast the value to long.

ipc.c: Use ftok() instead of SuperFastHash.

ftok(3) uses the identity of the named file to generate a key_t type
System V IPC key, which is easier than computing the key by hashing
the (resolved) pathname of the config file. This change allows to
get rid of the realpath() and the super_fast_hash() implementation.

If ftok(3) fails, presumably because the underlying call to stat(2)
fails, we now simply return a phony identifier, similar to what we did
before in this case. This eliminates the only possible failure path
in get_key_or_die(), so this function is renamed to get_key().

Remove --no-resume.

There is no real reason for this option. Resuming a previously
cancelled snapshot is generally a very good idea, so the option is
kind of pointless. Remove it.

dss-0.1.7.

A couple of fixes and improvements have accumulated over the last
year, so here's dss-0.1.7. Most likely this is going to be the last
0.1.x release.

Don't shadow cmdline_parser_params in main().

This avoids

dss.c:1519:32: warning: declaration of 'params' shadows a previous local [-Wshadow]

The warning is harmless, though.

ipc.c: Uninline get_key_or_die().

This function is rather big, so it's not clear whether it should
be inlined or not. Without the inline attribute, that's up to the
compiler to decide.

ipc.c: Constify parameter of get_key_or_die().

The function only reads from the location pointed at by the config_file
variable.

ipc: Fix error code returned by mutex_lock().

In the error case do_semop() already returns the error code which
corresponds to errno.

Improve log message for snapshot creation.

The log message that prints the name of the snapshot which is going to
be recycled is kind of interesting and deserves the "notice" severity.

The "creating new snapshot" message is a bit misleading in case we
decided to recycle a snapshot, so drop the word "new".

ipc: Simplify mutex_try_lock().

There is no need to actually obtain the lock. A single semaphore
operation will do just fine. With sem_op equal to zero and IPC_NOWAIT
the semop() call returns immediately, and the return value tells
whether the semaphore value was zero.

Rename the (static) function to mutex_is_locked() to indicate that
it performs only read-only operations on the semaphore set.

ipc: Make pid pointer optional.

This changes get_dss_pid() to handle the case where the caller passed
a NULL pid pointer. Conversely, if pid is not NULL, we now make sure
to initialize the given address in all cases.

The single caller currently never passes NULL, so this change is just
defensive programming, protecting against future users. Be liberal
in what you accept, be strict in what you return..

daemon: Do not change to /.

This is pointless because we immediately cd back into the destination
dir anyway.

build: Add two more warning options.

Both -Wunused-parameter and -Wshadow were added to gcc long ago. In
particular gcc-4.6.3, which ships with Ubuntu-12.04, supports them. It
should thus be safe to enable both warnings unconditionally.

dss.c: Add missing inclusion of <stdio.h>.

This is required for example for rename(2). Compilation succeeds without
the include only because the gengetopt header includes stdio.h as well and
we happen to include this header before fd.h.

dss: Make argument of parse_config_file() a boolean.

It is used as such, so there is no point to have an int here. Also
rename the argument from override to sighup to indicate that we
need to distinguish whether the function is called at startup or
because the dss process received SIGHUP.

Merge branch 'refs/heads/t/shadow-fix'

started 6 weeks ago, cooking for two weeks.

* refs/heads/t/shadow-fix:
  dss: Do not shadow a global declaration.

dss: Do not shadow a global declaration.

num_complete_snapshots is a local variable in
compute_next_snapshot_time(), but also the name of a public function
declared in snap.h, causing a warning on some (old) gcc versions.

This patch avoids the ambiguity and thus the warning by renaming the
variable. It was unusually long anyway.

Create html version of the man page with groff.

The html post processor of groff can directly create html, which is
expected to be of higher quality than the html generated by man2html. A
brief look at the "official" web site of man2html (as mentioned in the
description of the Ubuntu-14.04 package)

http://users.actrix.gen.nz/michael/vhman2html.html

shows why.

Convert INSTALL and NEWS to markdown format.

The grutatxt project is dead, so we have to switch to something else
eventually. Fortunately, there are only three files in grutatxt format,
one of which (README) does not need any changes. The other two are
converted to markdown format in this commit. This is a rather simple
matter since only section headings, links and preformatted text need
slight adjustments.

The commands in the Makefile are modified to run markdown(1) instead
of grutatxt(1).

Fix rsync exit handling in create mode.

The logic in handle_rsync_exit() is horribly broken in case dss is
run in create mode and the rsync process terminates unsuccessfully.

First we claim to restart rsync, which is wrong. Next we call the
post-create hook despite the documentation says that this hook is
only run on *successful* termination. Finally, we dereference a NULL
pointer to print the path of the snapshot.

Fortunately, all three issues are easy to fix by special casing create
mode in handle_rsync_exit().

dss.c: Remove pointless comment for main().

Clear case of "stating the obvious".

Remove orphaned snapshots even if disk space is not low.

Due to the previous patch, this is only executed if we have too many
snapshot anyway.

Always try to keep one snapshot for recycling.

Currently, if --keep-redundant is not given, we try to get rid of
outdated and redundant snapshots quickly, even if there is plenty of
free disk space available. However, as these snapshots can be used
for recycling, it seems to be worth to keep them around as long as
there are fewer snapshots available as configured.

This commit changes try_to_free_disk_space() to not remove snapshots
any more in this case. This patch should reduce disk I/O in the common
case where no snapshots need to be removed due to low disk space.

try_to_free_disk_space(): Explain what is going on.

This adds a comment which explains the conditions that must be
satisfied to get to this point in the function.

Allow to run in daemon mode without log file.

It's kind of silly to insist in having a log file in daemon mode.

This commit removes the dependency of --daemon on --logfile and makes
/dev/null the default log file. Consequently, running dss --daemon
--run without specifying --logfile no longer fails, and nothing will
be logged by default.

The documentation is updated accordingly.

Improve documentation of --keep-redundant.

The help text for --keep-redundant was rather convoluted. This commit
shortens the text with no essential semantic change.

The patch also removes the sentence that encourages to specify this
option if the destination directory is only used for snapshots. After
all, most file systems allow to create an insane number of files,
so keeping snapshots around forever can result in a file system that
can no longer be checked or repaired due to the excessive number of
used inodes.

Improve documentation of interval-related args.

Minor rewording of the help text for the --unit-interval option and
a new sentence which explains that the total number of snapshots
doubles if --num-intervals is increased by one.

README: Explain that there are no incremental backups.

This was unclear to an admin who had used dss for several years! So
maybe it is a good idea to explain the idea behind hardlink-based
backups a bit more.

This commit adds two new sentences to README, one for the admin and
another one for the user.

dss-0.1.6.

Merge branch 'refs/heads/t/signal_handler_improvement'

A single commit that was cooking for over a month.

Merge branch 'refs/heads/t/nullrw'

INSTALL: Reword sentence about gengetopt.

The latest version of gengetopt is two years old, so it hardly makes
sense to talk about a "recent version".

Also link to the gengetopt web page rather than to the FTP server.

daemon.c: Open /dev/null read-write.

While daemonizing we redirect stdin, stdout and stderr to /dev/null,
which is considered good practice. We should, however, open these
two devices in read-write mode rather than read-only, since not being
able to write to stdout/stderr might confuse rsync and the hooks.

NEWS: Fix typo.

This typo was introduced in commit 34653268 (Add NEWS file) years ago,
apparently by pasting the content from the freshmeat web page to the
NEWS file.

Merge branch 'refs/heads/t/max-errors'

The topic branch was cooking for about a week, and it was tested with
no problems on several multi-terabyte file systems.

* Rework restart logic, introduce --max-errors.
* Fix typo in help text of --daemon.

Improve signal handler.

The signal handler of dss has two issues: (a) it does not check the
return value of the write(2) call, and (b) it does not restore errno
on exit. The second issue might cause problems on systems where
write(2) sets errno also on success. Those problems would be very
hard to reproduce and debug. So it is probably a good idea to be
conservative here.

This commit fixes (a) by printing an error message and calling exit(3)
if the write to the signal pipe failed or resulted in a short write.
As for (b), we now save a copy of errno before the write(2) call,
and restore the old value on success.

Rework restart logic, introduce --max-errors.

It has happened several times in the past that dss made no progress
because the underlying rsync command terminates with exit code 13
(Errors with program diagnostics). Currently dss special cases this
exit code as a non-fatal error, i.e. it does not terminate but restarts
the rsync command after 60 seconds. If the problem is permanent,
no new snapshots will be created, but the exit hook is not called
either, which is unfortunate.

This commit tries to improve on this. With this patch applied, the
only non-fatal exit code from rsync is 24 (Partial transfer due
to vanished source files), which is actually considered success.
All other non-zero exit codes cause dss to restart the rsync command,
but only at most N times, where N is the argument given to the new
--max-rsync-errors option.

Fix typo in help text of --daemon.

str.c: Remove vsnprintf() workaround for old glibc.

Since glibc-2.1 was released 16 years ago, the workaround for glibc-2.0
is no longer necessary. Even the example code of printf(3) dropped it.

str.c: Get rid of VSPRINTF macro.

It has only one user, make_message(), so it's simpler to include the
code there.

Assorted typo fixes in comments.

Fix typo in documentation of --logfile.

Shut down the signal subsystem on exit.

No biggy since we exit anyway a few lines later, but still..

tv.c: Remove unused functions.

Quite a few public functions of tv.c are not used anywhere in dss,
so let's get rid of them. We can easily add them back in case they
are neeed in the future.

Found by cppcheck.

str.c: Remove pointless initialization.

The variable p is initialized to a different value a few lines later
and the value set in the definition is not used in between.

Found by cppcheck.

Remove non-functional SEE ALSO links from index.html.

It's nice to have references to ssh and rsync in the SEE ALSO section
of the man page. On the web page, however, they do not add much value
since the links generated by man2html do not work. This patch omits
the broken links.

NEWS update

Change background color of web pages to white.

The old colors looked a little like the 90s ;)

Merge branch 'refs/heads/t/min-complete'

NEWS: Fix indentation of 0.1.5 items.

The generated html looked terrible. No real changes.

index.html.in: Fix gitweb link.

Apparently the symlink workaround for the gitweb pages on
git.tuebingen.mpg.de does not work any more although the symlink
dss->dss.git is still in place.

This commit changes the link on the web page to include the .git
suffix.

Introduce --min-complete.

Currently dss cowardly refuses to remove the last complete snapshot
even if disk space is low, and fails if there is not enough disk space
left for a second snapshot. However, in some situations it is more
important to have a recent snapshot and to to keep dss up and running.

This commit introduces a new integer option, --min-complete, which
defaults to one to resemble the old behaviour.

If it is set to zero, dss will happily remove the last complete
snapshot, even if it is used as the reference directory for rsync's
--link-dest option. This is dangerous, but it's the only way to keep
dss going.

Conversely, --min-complete may be set to a value greater than one
to guarantee there is always a certain number of complete snapshots
available.

Change email address and URLs.

The web and email service of systemlinux.org was down for two
weeks. Meanwhile the dss web pages found a new home at the MPI campus
of Tübingen.

This commit changes the email addresses and the home page URL.

Silence clang warnings.

The -Wno-sign-compare option is supposed to not print the noisy
warnings for comparisons between signed and unsigned values.
Currently, in DEBUG_CFLAGS this option is followed by -W which causes
clang (but not gcc) to turn on these warnings again. As CFLAGS contains
-Wall, the -W option was redundant anyway, so this patch removes it.

dss-0.1.5.

Merge branch 't/exit_fix'

Was cooking since 2013-10.

Merge branch 't/dia'

The single commit of this branch is more than one year old. I totally
forgot about it, but here it is:

311ec5 Switch logo from skencil to dia.

The web page has been updated to contain the new image.

Kill children on fatal errors.

If dss is about to die because it received SIGINT or SIGTERM, we first
restart the rsync process by sending SIGCONT, then send SIGTERM to
both the rsync and the rm process to get rid of any child processes.

This works fine, but there are other fatal errors for which we miss
to clean up as thoroughly, most importantly if there is not enough
free disk space for a single snapshot.

This patch moves the signal-related cleanup part to the new function
kill_children(), and changes handle_signal() and com_run() to call
this function right before the exit hook is invoked.

Trivial: Remove trailing semicolon.

rsync: Remove hardcoded --quiet option.

When running in daemon mode, the stdout and stderr stream of dss and
all its child processes are redirected to /dev/null. In particular any
output from the rsync process is discarded. Therefore, whenever a new
snapshot is created, dss currently passes --quiet to the underlying
rsync command, along with --archive and --delete.

However, as was pointed out by Sebastian Schultheiß, if the rsync
command fails for unknown reasons, the --quiet option complicates
debugging for the questionable benefit of saving the I/O for a few
writes to /dev/null.

This patch removes the --quiet option.

Merge branch 't/zero-rsync-fix'

Reject insane number of intervals.

Nobody needs more than 2^30 snapshots. More importantly, values
larger than 32 for --num_intervals cause an integer overflow in
desired_number_of_snapshots() because the number of snapshots in
interval zero does not fit in an unsigned int in this case.

This patch adds a test to check_config() that rejects values larger
than 30 for the --num_intervals option.

Many thanks to Klaus Kopec for pointing out this bug.

Don't create two snapshots in the same second.

This can only happen if all of the follwing are true:

(a) source and destination directories are small
(b) rsync completes successfully within one second
(c) At most two snapshots are missing

In this case the rename() call which changes the snapshot name from
*-incomplete to the proper name fails for the second snapshot with
EEXIST. This is because the previous snapshot name coincides with
the name of the second snapshot.

The fix is a bit ugly but also non-invasive and simple: Just sleep
one second in this case.

Merge branch 't/rename_system_files'

Has been cooking for several weeks. The conflicts

daemon.c
exec.c
file.c
ipc.c
sig.c

are trivial and can be resolved easily.

Switch logo from skencil to dia.

The sketch/skencil project appears to be inactive for years, and
it is no longer shipped on recent Linux distributions. This commit
replaces the sketch source file dss.sk by dss.dia, a source file for
dia, an GTK+ based diagram creation program. The new logo looks very
similar to the old one but was created from scratch.

dia allows to convert a .dia file to PNG image data. This patch also
adjusts the Makefile to produce the dss.png logo from dss.dia.

Rename source files which also exist as system headers.

As pointed out by Daniel Richard G. some of the dss header files
are named the same as system header files.

This patch renames these headers as well as their corresponding .c
files. Specifically, error.h, fd.h, signal.h, string.h and time.h
become err.h, file.h, sig.h, str.h and tv.h.

Make the dss log facility C89 conform.

Variadic macros were introduced in C99, so they are not supported on
ANSI C compilers. Since currently all DSS_*_LOG macros are variadic,
we need a replacement for these. Moreover, since not all compilers
support __func__ or an equivalent, we need to check for this feature
as well and provide a workaround if necessary.

This patch introduces the new public function dss_log_set_params()
which saves the given log level, filename, line number and the
function name in global variables. The DSS_*_LOG macros are changed
to receive a single argument only, which is the usual variadic list,
enclosed in additional parentheses.

The new DSS_*_LOG macros first set the log parameters by calling
dss_log_set_params(), then call dss_log() with the variadic list as
the argument. dss_log() is patched to print the function name only
if __func__ is supported and fall back to file name and the line
number otherwise.

All DSS_*_LOG() calls are changed to the new syntax.

ipc.c: Eliminate per-field struct initializations.

This replaces the C99-only initializations in mutex_lock() and
mutex_try_lock() by equivalent but portable code.

Have foo.c #include foo.h.

This is both to ensure function signature consistency, and to
eliminate GCC's "no previous declaration for _____" warnings.

Mark find_oldest_removable_snapshot() as static.

It is not used outside the source file in which it is defined.

Merge branch 't/gcc-compat_fix'

* e1f886 Only define gcc function attributes on gcc.

Merge branch 't/cleanups'

The changes in this branch are an attempt to make dss compile cleanly
with the more strict compiler flags (GCC 4.6 on Linux).

    -pedantic -fno-common -W -Wall -Wcast-align -Wformat=2
    -Wpointer-arith -Wundef -Waggregate-return -Wcast-qual
    -Wmissing-declarations -Wnested-externs -Wstrict-prototypes

This is only a first step that addresses the easier warnings. Some,
like the ones stemming from the variadic macros, have yet to be fixed.

* 9e6c2f Remove some debug messages.
* 899f88 string.c: Fix a statement-before-declaration issue.
* 83ebb4 Remove trailing commas.
* 2ed0d7 snap.h: Fix HSA_ITEM.
* 508350 Fix "comma after last element" warning.
* 97fbf4 compare_snapshots(): Add const keyword.
* b28495 Avoid per-element initializers.
* 9528cf dss.c: Fix initialization of argv[].
* 4526f9 dss.c: Remove redundant const.
* 2183c6 Makefile: Split CPPFLAGS.

Conflicts:
error.h

Merge branch 't/ipc'

4d9f41 mutex_get(): Change parameter from key_t to int.
55c90e Implement --reload.
492928 Add the --kill subcommand.
dd42f7 Use semaphore locking to avoid starting dss multiple times.
17eea8 Introduce get_config_file_name().

That topic was cooking in next for a quite some time now.

Only define gcc function attributes on gcc.

These gcc extensions help the compiler optimize function calls,
but are unavailable if dss is not compiled with gcc.

This patch defines the corresponding macros to empty if __GNUC__
is not defined, or if the gcc version is too old to support the
particular function attribute.

Remove some debug messages.

These were only helpful during development and are commented out
for quite some time now. Remove them.

string.c: Fix a statement-before-declaration issue.

Remove trailing commas.

snap.h: Fix HSA_ITEM.

This changes the second definition of HSA_ITEM to avoid C99
subscripted element initializers.

Fix "comma after last element" warning.

This changes the definition of DSS_ERRORS so that it includes the commas,
and removes the comma from both definitions of DSS_ERROR. This
avoids "comma after last element" warnings, which on some compilers
produces an error.

compare_snapshots(): Add const keyword.

This fixes a "cast drops const qualifier" warning.

Avoid per-element initializers.

Per-element struct initializers are not supported in ANSI C. This
construct doesn't gain much in terms of readability, and breaks
compatibility with older/stricter compilers.

dss.c: Fix initialization of argv[].

argv[] can't be declared in this way because the initializers are not
computable at compile time. GCC allows this construct, but stricter
compilers don't.

dss.c: Remove redundant const.

hook_status_description[] had a redundant const keyword, per GCC.

Makefile: Split CPPFLAGS.

-W*/-O*/-g options belong in CFLAGS, not CPPFLAGS. CPPFLAGS is for
preprocessor-specific (-D*/-I*) options.

mutex_get(): Change parameter from key_t to int.

The two callers obtain the key from get_key_or_die(), which
returns int. So pass an int anyway. This fixes a warning on
NetBSD:

ipc.c:263: warning: format '%x' expects type 'unsigned int', but argument 4 has type 'key_t'

error.h: Remove is_errno().

This inline function is unused.

Merge branch 't/exec_cleanups'

06a23c Simplify exec functions.

Was cooking quite long and no problems showed up.

Implement --reload.

This is literally the same as --kill, the only difference being that
SIGHUP rather than SIGTERM is sent.

Add the --kill subcommand.

It works as follows: Whenever a semaphore operation is performed, the
PID of the process is stored in the sempid field of the semaphore.
This PID can be obtained from a different process by calling semctl
with the GETPID command.

com_kill() first tries to acquire the lock by calling the new
mutex_try_lock() function of ipc.c. In contrast to mutex_lock(),
mutex_try_lock() only operates on the first semaphore in the semaphore
set, leaving the sempid field of the second semaphore unchanged. If
mutex_try_lock() succeeds, no running dss process is holding the lock
and the kill command fails. Otherwise, some dss process is running
whose PID can be obtained by calling semctl() on the second semaphore.

Use semaphore locking to avoid starting dss multiple times.

It's trickier than one might expect but it is hopefully also much
better than any pidfile-based approach.

This patch adds ipc.c and ipc.h containing the public lock_dss()
function which acquires a semaphore-based lock whose key is based
on the hash of the resolved path name of the dss config file. This
allows different instances of dss to coexist.

All semaphore operations are called with both the SEM_UNDO and the
IPC_NOWAIT flag. SEM_UNDO guarantees that no stale lock remains after
dss was killed by SIGKIlL while IPC_NOWAIT makes the call to lock_dss()
fail if another process is already holding the lock.

The prune/create/run commands simply take the lock at startup and
exit if it could not be acquired.

The underlying semaphore set contains two semaphores. This is necessary
to implement the --kill subcommand which is done in a subsequent patch.

Introduce get_config_file_name().

ATM, the config file name is computed in parse_config(). However, for the ipc
stuff we'll need that information as well, so move the computation to a separate
helper function().

doc: Add a second example config file.

This commit provides another example for the INSTALL file. It
illustrates the use of some more sophisticated config options of dss.

Many thanks to Ivo Welch who suggested this change.