Fix documentation of filter->post-select().

The ->post_select() methods return an integer these days and should
*not* set the ->error field of the task struct directly.

ipc.c: Fix typo in comment.

aft.c: Remove a stray "*" in a comment.

Move com_select_callback() closer to com_select().

It's considered good style to have the command handler and it's
callback next to each other. No actual changes.

buffer_tree.c: Add documentation of btr_parent().

This function was introduced in commit 37e0dfe7 (check_wav: Ask parent
nodes before falling back to defaults) without documentation.

ggo.c: Document return value of printf_or_die().

Commit b59a3c41 (filter: Wrap lines in the available filter list)
changed the return value of this function from void to int but missed
to update the documentation.

Mood: Document return value of moods_event_handler().

Just to make doxygen happy.

net.c: Add documentation of flowopt_new().

It's not obvious that the returned structure does not need to
be freed by the caller, so let's document this fact.

net: Remove unused flowopt_add_bool().

recv.h: Fix comment indentation.

Remove some duplicate semicolons.

Remove some unused error codes.

Quite a few error codes have become unused, but the stale entries
of error.h remained. Unfortunately, we have no way to spot these
automatically.

Doxyfile: Predefine HAVE_CLOCK_GETTIME.

Fixes the following doxygen warning:

time.c:227: Warning: include file sys/time.h not found, perhaps you forgot to add its directory to INCLUDE_PATH?

audiod: Close filters in reverse order.

Otherwise, a subsequent filter might refer to a buffer reference of
the previous filter, accessing freed memory. This is not a bug right
now, as audiod only closes filters after the full buffer tree has
become inactive, i.e. after all buffer tree nodes have unregistered
their task. It's cleaner to reverse the loop though, and it has no
additional cost.

opusdec: Get rid of opusdec_pre_select().

The generic one should do just fine and the additional 100ms timeout
should not be necessary.

opusdec: avoid __STDC_VERSION__ warning.

opusdec_filter.c indirectly includes opus_types.h which checks whether
__STDC_VERSION__ >= 199901L. However, at least some gcc versions
don't define __STDC_VERSION__ which results in

warning: "__STDC_VERSION__" is not defined

For example, this happens on Ubuntu lucid, which ships gcc-4.4.3.

This patch gets rid of the warning by defining __STDC_VERSION__
if necessary prior to including the opus_types header.

afh: Initialize audio format handlers only once.

afc.c calls afh_init() twice. This does not really hurt as this
function is idempotent, but it causes the initialization log messages
to be printed twice.

This gets rid of the additional call to afh_init() which crept in
in commit 042767ce (Use self-made help to avoid recompilations on
version changes).

mp3_afh: Use symbolic constants for id3 tag identifiers.

Merge branch 't/opus'

Was cooking for two weeks with no problems.

273756 The opus decoder.
7007ae The opus audio format handler.
8bcf75 ogg/opus: Infrastructure.
53133e speex: Don't export spx_ctl().

Merge branch 't/versioning_improvements'

Cooking for ~2 weeks.

15e99a version.c: Mark version_git() as const.
9bdebf Remove CODENAME macro.
be2f6b gui: Use version_single_line().
d60dae Improve man page layout.
5dbc9a afh/play: Include supported audio formats in help output.
042767 Use self-made help to avoid recompilations on version changes.
48f1fc Provide "purpose" texts.
aa74a9 Revamp ggo help.
9f7a49 afh_recv: Replace ggo text section by description.
b59e0e Make gengetopt descriptions work.
06b3e7 Introduce version.c to limit recompilation on version changes.
75feac Make all commands print git version and improve version string.
b01605 Avoid unwanted log messages during startup.
625fdb Don't check return value of command line parsers unnecessarily.
533b03 Build receivers, filters and writers without -h and -V support.
b59a3c filter: Wrap lines in the available filter list.
9e56d3 audioc: Print config file errors.
e5264d doc: Rewrite udp sender description
5ec373 client: Fix typo in comment.
6d5159 client: Remove duplicate include.

version.c: Mark version_git() as const.

Fixes the following warning on gcc-4.8.1:

version.c:13:13: warning: function might be candidate for attribute 'const' [-Wsuggest-attribute=const]

i9e: Fix memory leak in clear_bottom_line().

In clear_bottom_line() we call readline's rl_copy_text() which
allocates a buffer for the given range of the current input line. But
we never free this buffer, which results in a memory leak. This patch
plugs the leak.

Handle empty command lines properly.

Both para_client and para_audioc create an argument vector from the
given command line using create_argv(). If the command line contains
only whitespace characters, this vector has length zero, and argv[0]
is NULL.

We missed to check for this at at least three places in audioc.c,
client.c and audiod_command.c, which resulted in crashes due to NULL
pointer dereferences or failed assertions.

These bugs can easily be triggered by starting para_client or
para_audioc in interactive mode, entering a single space character
and hitting return.

This patch adds the missing checks to prevent the crashes.

Merge branch 't/interactive'

Was cooking for almost two weeks.

f8931d Simplify i9e_line_handler.
f99dbe i9e: Fix a prompt display issue
cf39e4 audioc: Abstract out connection code.

Improve text on the download web page.

Enumerate the possible ways to download paraslash and explain when
each option is most suitable.

gui: Fix off-by-one in add_spaces().

Commit e90c6c0a (Speed up add_spaces().) changed add_spaces() to print
space characters in chunks rather than one at a time. It introduced
space[], an array of whitespace characters, which is written entirely
if there are more spaces to print than the size of the array. However,
in the calculation of how much was printed so far, we missed the fact
that sizeof(space) includes the terminating NULL byte, so this number
is in fact the number of space characters *plus one*.

Consequently, we printed too few space characters. This resulted in
parts of the previous string still being visible in the top window
of para_gui.

Merge branch 't/compress'

Well tested an cooked.

0a6c0e compress: Further optimize inner loop.
be761d compress: Remove log statement in inner loop.
15a54f compress: Avoid PARA_ABS and PARA_MAX in inner loop.
28c03c compress: Compile with -O3.

Merge branch 't/oss_error_message_fix'

9e32ff oss mixer: Improve error message.

Remove CODENAME macro.

This macro is no longer used, so we may remove it from Makefile.in.

gui: Use version_single_line().

No need to reinvent the wheel.

Improve man page layout.

This changes the output of --help, --detailed-help and --version
so that the man pages generated from this output by help2man look
much nicer.

Specifically, name and purposes are printed in a single line and
the version text now contains also build data, build system and the
compiler version.

Also the codename is no longer printed in version_single_line(),
since this caused the top and bottom labels of the man pages to
look quite ugly.

afh/play: Include supported audio formats in help output.

This is useful information, and it is simple to do, so include it in
the help.

Use self-made help to avoid recompilations on version changes.

This provides print_help() for all remaining commands so that we can
get rid of the gengetopt generated help output completely.

Hence the *.cmdline.[ch] files no longer depend on git-version.h
which saves a lot of recompilations.

Provide "purpose" texts.

This text will be printed right after the program name in the --help
output. For para_afh, the inline text becomes redundant, so this text
is removed.

Each executable gets a purpose text, and for receivers, filters,
writers the purpose will be printed as part of the help output of
para_audiod, para_filter. para_recv and para_write.

Revamp ggo help.

This adds usage and description fields to struct ggo_help and
changes ggo_print_help() to optionally print these.

The boolean detailed_help flag of ggo_print_help() is replaced by a
bitmask which lets the caller specify what to print. Four pre-defined
masks are used to print the normal help, the detailed help, the help
for modules (receivers, filters, writers) and the detailed module help.

The new macro DEFINE_GGO_HELP can be employed to create a struct
ggo_help from a gengetopt structure.

afh_recv: Replace ggo text section by description.

This way the text shows up only when --detailed-help is given.

Make gengetopt descriptions work.

With gengetopt's text and description options it is not possible to
print a text only when --detailed-help was given, but not when only
--help is given.

Moreover, headers generated with old versions of gengetopt do not
export the description text.  However, declaring it unconditionally
causes compiler warnings on new systems.

To circumvent these problems, we introduce a new test for configure
which checks whether the description string is declared. If it is not,
we simply append the declaration to the *.cmdline.h files.

This change allows to move the description string of para_play to
the gengetopt source file.

Introduce version.c to limit recompilation on version changes.

Currently version.h includes git-version.h which changes whenever
a different commit is checked out or the working tree becomes dirty
because a file has been modified. Consequently, all .c files that
include this header must be recompiled in this case.

To limit the number of recompilations, this commit introduces
version.c, which contains functions that return the various types of
the version string. It is now the only file that includes version.h,
so only version.o must be rebuilt if git-version.h changes.

This also adds the build date, OS and CC version to the version output.

Make all commands print git version and improve version string.

Currently the format of the first line of the help output varies
between executables, for example:

para_afh git (0.4.12.12.g15a4: spectral gravity)
para_audioc git

This difference comes from the fact that para_afh has its own
->print_help method which uses the VERSION_SINGLE_LINE macro of
version.h while para_audioc relies on gengetopt's help output.

The latter uses the make variable PACKAGE_VERSION which gets
initialized at configure time through the second argument in AC_INIT
of configure.ac. This value is either the version number for or the
string "git".

It's a good thing to have the abbreviated git version encoded in
all executables, so this commit changes the argument of gengetopt's
--set-version to the git version string including the codename. With
the patch applied, the output of all commands looks like this if
--version was given:

para_filter 0.4.12.12.g11d7 (spectral gravity)

To make sure things stay consistent, the patch introduces the
VERSION_SINGLE_LINE macro and changes all commands to use it instead
of open coding the version string.

Avoid unwanted log messages during startup.

Regardless of the given loglevel, para_recv currently prints log
messages like these at startup:

afh_init: initializing mp3 handler
afh_init: initializing ogg handler
afh_init: initializing aac handler
afh_init: initializing wma handler
afh_init: initializing spx handler
afh_init: initializing flac handler

That's because recv_init() is called before the command line arguments
are parsed, so the loglevel has not been set at this point. Other
programs have similar problems.

Fix these problems by always setting the loglevel right after a parser
has been called so that the init functions run *after* loglevel has
been set.

Don't check return value of command line parsers unnecessarily.

All gengetopt parsers except the one for para_client are generated
without the --no-handle-error option, i.e. these parsers exit on errors.
Hence it is pointless to check return values.

Build receivers, filters and writers without -h and -V support.

This is not needed since the help is printed by the driving application.
It allows to get rid of an ugly "p += 3" statement in ggo.c.

filter: Wrap lines in the available filter list.

Currently para_filter -h and para_audiod -h print the available
filters in a single line which exceeds 80 characters if many
filters are supported.

This patch makes printf_or_die() return the number of characters
printed.  This allows to add line breaks to format the filter list.

audioc: Print config file errors.

Currently para_audioc fails silently if the config file contains
errors. This patch makes it print a proper error message in this case.

doc: Rewrite udp sender description

This text was rather badly written. Replace it with better English.

client: Fix typo in comment.

client: Remove duplicate include.

The client.cmdline.h header file was included twice.

Merge branch 't/stdin_stdout_fixes'

Was cooking for almost a month.

b99b4a stdin/stdout: Restore fd flags on shutdown.

Conflicts:
stdin.c
stdout.c

Fix help text of com_touch().

It is the amp filter rather than the compress filter that makes use
of the amplification value stored in the audio file table.

Simplify i9e_line_handler.

The line handlers of all three users of the i9e API (play, client
and audioc) return immediately if the passed line is NULL or the
empty string. Hence we may call the line handler only if there is a
non-empty line to dispatch.

Moving the check for a non-empty line to generic i9e code simplifies
the three line handlers a bit and avoids code duplication.

i9e: Fix a prompt display issue

If a line handler calls PARA_XXX_LOG() to write a log message before
attaching a buffer tree node, the prompt is not displayed properly.

Fix this by attaching a dummy btrn before the line handler is called.

audioc: Abstract out connection code.

This way we get a nice error message in interactive mode when
para_audiod is down. Before:

para_audioc> help
i9e_line_handler: No such file or directory

After:

para_audioc> help
connect_audiod: could not connect /var/paraslash/audiod_socket.schubert
i9e_line_handler: No such file or directory

Merge branch 't/gui_improvements'

Was cooking for more than one month.

bf1831 string: Speed up xvasprintf().
bcc083 string: Add discard feature for for_each_line().
e3868d string: Simplify return value of for_each_line().
d1f0f0 string: Simplify for_each_line().
23b121 string: Clean up for_each_line() and related functions.
6256ed string: Replace the for_each_line_modes enum by a bitmap.
14e689 gui: Don't sleep before executing the status command.
e90c6c gui: Speed up add_spaces().
20e2c6 gui: Rename do_exit().
ef0508 gui: Remove superfluous cmd_died.
d7562b gui: Check stdin for readability.
a44fa6 gui: Discard overlong input lines.

Conflicts:
gui.c

The opus decoder.

Implementation is similar to the speex decoder, in particular meta
data handling is almost identical.

The opus audio format handler.

This fills the dummy files opus_afh.c and opus_common.c which were
introduced in the previous commit with content.  One function,
opus_parse_header(), will also be needed by the decoder to
be introduced in the next commit. So this function belongs to
opus_common.c and must be public.

ogg/opus: Infrastructure.

This adds tests for libopus to configure.ac and minimal (non-working)
implementations of the ogg/opus decoder and audio format handler.

speex: Don't export spx_ctl().

This is only used from spx_common.c, so make it static and kill
the prototype in spx.h.

Merge branch 't/doc'

Simple enough and cooking since 2013-05-05.

e82be0 manual: Add a new paragraph for installing dependencies.
1d6f5f manual: Add missing references of two optional packages.
4a6061 check_wav.c: Fix documentation of check_wav_post_select().
f9c625 Add two missing Copyright headers and file annotations.
16af9d Add documentation of public functions in check_wav.c.

Merge remote-tracking branch 'mpi/master'

Fix compilation on Ubuntu precise.

This distro ships glibc-2.15 where clock_gettime() is part of the
realtime library librt. So all executables which call clock_gettime()
must be linked with -lrt. The configure script detects this and adds
-lrt to LDFLAGS. However, -lrt must come *after* the objects to be
linked together, which is currently not the case.

Fix this by moving $(LDFLAGS) to the end of the recipe for the targets
of all executables.

filter_common.c: Fix two typos in comment.

alsa writer: Do not print uninitialized data.

ALSA's snd_output_buffer_string() returns the current size of valid
data in the returned data buffer, but this buffer is not guaranteed
to be zero-terminated.

Currently alsa_init() ignores this fact and prints the buffer up to
the first NULL byte.  Therefore it may print garbage that follows the
valid data in the buffer. If there is no zero byte after the data,
it may even segfault.

Fix this bug by using memchr() instead of strchr() and carefully
tracking the number of bytes processed.

file writer: Use xwrite() instead of plain write().

Currently the file writer's ->post_select() sets t->error to -1 on
errors, rather than using a proper error code. This may result in
a segfault when this number is passed to para_strerror().

Replacing the call to write() by xwrite() not only gives a proper
error code but also treats EAGAIN as a non-fatal error.

Merge branch 't/sched_improvements'

This topic has been cooking for a month. During this period, one
problem on BSD has been found and fixed.

3ad5b0 Fix build on FreeBSD
484e75 sched: Rename new_post_select back to post_select.
74c880 sched: Kill old ->post_select variant.
c77e19 grab client: Switch to the alternative post select method.
38aeac client supervisor: Switch to the alternative post select method.
e009fa client exec: Switch to the alternative post select method.
742718 i9e: Switch to the alternative post select method.
2e6b8f vss: Switch to the alternative post select method.
6e83b4 stdout: Switch to the alternative post select method.
1995ce stdin: Switch to the alternative post select method.
88b0ec audioc: Switch to the alternative post select method.
b210e8 afs command task: Switch to the alternative post select method.
12f683 afs signal task: Switch to the alternative post select method.
ccef24 server signal task: Switch to the alternative post select method.
a6dabd server command task: Switch to the alternative post select method.
855c53 write: Switch to the alternative post select method.
58b74b play: Switch to the alternative post select method.
cf4982 afh_recv:  Switch to the alternative post select method.
4dc05b client: Switch to the alternative post select method.
043fd6 audiod: Switch command_task to the alternative post select method.
ce462a audiod: Switch the status task to the alternative post select method.
a7f2d1 audiod: Switch signal task to the alternative post select method.
ba2f65 osx writer: Switch to the alternative post select method.
3642d2 oss writer: Switch to the alternative post select method.
c29db3 file writer: Switch to the alternative post select method.
36875c ao: Switch to the alternative post select method.
3b3049 alsa: Switch to the alternative post select method.
60b853 wmadec: Switch to the alternative post select method.
6c8719 wav filter: Switch to the alternative post select method.
03e915 spxdec: Switch to the alternative post select method.
24bbc5 resample: Switch to the alternative post select method.
4ca80f prebuffer: Switch to the alternative post select method.
a55083 oggdec: Switch to the alternative post select method.
806d26 mp3dec: Switch to the alternative post select method.
7dcaf5 flacdec: Switch to the alternative post select method.
4dc9b9 fecdec: Switch to the alternative post select method.
f6e2cb compress: Switch to the alternative post select method.
ac3371 amp: Switch to the alternative post select method.
7c2c68 aacdec: Switch to the alternative post select method.
b333e0 dccp_recv: Switch to the alternative post select method.
00e793 udp_recv: Switch to the alternative post select method.
9c00a7 sched: Provide alternative post_select variant.
24758c Replace gettimeofday() by clock_gettime().
01f802 sched: Get rid of (pre)select shortcuts.
5bb44a audiod: Avoid delay when closing slot.

Conflicts:
string.c

configure.ac: Do not print play objects.

This is a debug statement from the early days of development of
para_play. It can safely be removed.

Fix build on FreeBSD

Commit 24758c5f (Replace gettimeofday() by clock_gettime()) removed
the inclusion of sys/time.h from several files since this header was
believed to be needed only for gettimeofday(), which was removed in
the same commit.

However, this broke the build on FreeBSD since sys/time.h
also pulled in the declaration of u_short, which is required by
/usr/include/netinet/udp.h. Therefore the compilation of udp_send.c
failed with

/usr/include/netinet/udp.h:42: error: expected specifier-qualifier-list before 'u_short'

This patch changes udp_send.c to include sys/types.h, which provides
the missing declaration.

Merge branch 't/utf8'

Was cooking since 2013-03-10.

a946af string.c: Fix typo in documentation of skip_cells().
251394 Switch to HTF-8 for web pages.
09c6bc gui: Try to link against libncursesw.
36f38a UTF-8 support for para_gui.
a99804 mp3_afh: Switch to UTF-8 encoding.
f78b53 gui: Don't compute string length unnecessarily.
6224f7 Get rid of unused HAVE_NCURSES define.
6cd788 Fix --with-curses configure option.

oss mixer: Improve error message.

If /dev/mixer does not exist, para_fade fails with

main: No such file or directory

This is a rather bad error message, since the name of the missing file
is not mentioned. This patch makes oss_mix.c print the additional line

 oss_mix_open: could not open /dev/mixer

manual: Add a new paragraph for installing dependencies.

This allows to install all required and optional packages with
a single command.

stdin/stdout: Restore fd flags on shutdown.

The stdin/stdout code should restore the flags to the old value to
avoid surprises, for example in shell scripts.

This changes stdin.c and stdout.c to save the old value. It is
restored in ->post_select when the buffer tree node is removed and
no more I/O takes place.

wma: Fix sparse error.

wma_common.c defines wma_log2() with __attribute__ ((const)), but the
declaration in wma.h lacks this attribute. Sparse does not like that
and fails with

wma_common.c:147:15: error: symbol 'wma_log2' redeclared with different type (originally declared at wma.h:28) - different modifiers

Add the const attribute also to wma.h.

aacdec: Fix check of return value of NeAACDecInit2().

This function returns (char)-1 on errors and zero on success. Checking
whether the return value is negative is incorrect on systems where
char is unsigned.  On raspberry/ARM, gcc complains:

aacdec_filter.c:126:6: warning: comparison is always false due to limited range of data type [-Wtype-limits]

Fix this by checking agains zero instead.

manual: Add missing references of two optional packages.

The curses lib and libsamplerate are both optional but were not
mentioned in the "Requirements" section. This patch adds both.

string: Speed up xvasprintf().

This avoids to call vsnprintf() twice in the common case where the
result is small.

The running time of a simple test case that called this function in
a loop improved from 13s to 8s due to this change.

string: Add discard feature for for_each_line().

This adds the new FELF_DISCARD_FIRST flag which instructs
for_each_line() to discard everything up to the next newline.

The new feature is only used by para_gui. When para_gui detects
a partial overlong input line, it ignores this data and passes the
FELF_DISCARD_FIRST flag in subsequent calls to for_each_line(). Hence
output continues at the next line.

string: Simplify return value of for_each_line().

No caller used this function for counting lines, so simplify it by always
returning the number of bytes not processed.

string: Simplify for_each_line().

No user calls this with line_hander == NULL, so remove the special treatment
of this case.

string: Clean up for_each_line() and related functions.

While for_each_complete_line() is a static function, there are two
public functions, for_each_line() and for_each_line_ro(), which are
implemented as simple wrappers for the static one. The only difference
between the two is that for_each_line_ro() sets the FELF_READ_ONLY
bit while for_each_line() does not.

Since we are about to add another bit of information soon, let's make
the bitmap and the static function public, and remove the two wrappers.
All callers are changed to pass an additional "unsigned flags" to
indicate whether they want the read-only behavior.

Documentation is updated accordingly.

string: Replace the for_each_line_modes enum by a bitmap.

Currently we pass an "enum for_each_line_modes" as the first argument
to for_each_complete_line(). The parameter is effectively a boolean
since the enumeration defines only two possible values.

For the upcoming discard feature of for_each_line_modes() we'll need
to pass another bit of information, so this patch changes the type of
the first argument to for_each_complete_line() to unsigned and treats
it as a bit array. The only bit defined so far is LINE_MODE_RO, with
unchanged semantics.

The two callers are updated to reflect this change.

gui: Don't sleep before executing the status command.

This results in uncacceptable delays when the status command fails
for any reason, for example because the server is down.

Replace this code by introducing a struct timeval variable "next_exec",
which stores the earliest possible time to restart the status command.

Move all status fetching code before the select() call in do_select()
to open_stat_pipe() and rename the function to status_pre_select(),
which is more appropriate.

gui: Speed up add_spaces().

The calls to waddstr() in this function showed up in profiles. So
print the full string at once instead of calling waddstr() for each
character.

gui: Rename do_exit().

This function sends SIGTERM to every process in the process group of
para_gui and dies thereafter. So kill_pg_and_die() is more descriptive
than the old name.

gui: Remove superfluous cmd_died.

We might as well directly refer to cmd_pid which is set to zero in the
signal handling code after the process exits.

gui: Check stdin for readability.

If the select_loop of para_gui runs in getch or command mode we
currently wait a full timeout period before checking for pending
input.

This patch adds stdin to the set of file descriptors monitored by
select so that a key press causes select() to return immediately.

gui: Discard overlong input lines.

If an external command produces output without newlines, the current
code ends up calling read_nonblock() with a buffer size of zero which
triggers the assertion in readv_nonblock().

Increase the output buffer to 32K and fix the problem by simply
discarding all input if the input buffer is full and contains no
newline character.

A better fix would be to discard everything until the next newline
character is read, but this requires more work, so let's go with this
simple fix for now.

Merge branch 't/allow_zero_btr_add'

Was cooking for over a month.

sched: Rename new_post_select back to post_select.

sched: Kill old ->post_select variant.

It has no more users.

grab client: Switch to the alternative post select method.

client supervisor: Switch to the alternative post select method.

client exec: Switch to the alternative post select method.

i9e: Switch to the alternative post select method.

vss: Switch to the alternative post select method.

stdout: Switch to the alternative post select method.

stdin: Switch to the alternative post select method.

audioc: Switch to the alternative post select method.

afs command task: Switch to the alternative post select method.

afs signal task: Switch to the alternative post select method.

server signal task: Switch to the alternative post select method.

server command task: Switch to the alternative post select method.