Tanu, Felipe,
Writing up some text now for the --check option. Further below is what I have
so far. A lot longer than the original, but it attempts to cover everything
that has been mentioned in the thread thus far.
However, while verifying some of the statements made in the proposed text (by
doing experiments with $XDG_RUNTIME_DIR and $HOME settings and looking at debug
output) I found some discrepancies between the experiment results and some
statements made earlier in the thread. Can you comment on these please:
1. > ...if XDG_RUNTIME_DIR isn't set at all, then the check assumes that
> HOME[1] is set correctly.
The experiments seem to indicate that if XDG_RUNTIME_DIR is EITHER unset
OR if it points to a directory or pid file which is inaccessible or non-
existent, then the $HOME approach is used.
2. In the latter case ($HOME approach) it seems that on my system (Arch linux)
the directory in which the xxxx-runtime file is located is not
$HOME/.config/pulse (as was stated earlier in the thread), but $HOME/.pulse.
Are there any other possibilities?
3. Also pertaining to the $HOME approach, in which the runtime dir is named
as "xxxx-runtime", where xxxx is a hex string: I'd like to at least say
a few words about what that "xxxx" is. Is it a per-session ID? Or per-seat?
Or what?
4. Even better than answering 1-3: Do you know of any extant PulseAudio doc
that could be cited which describes in detail the way in which the
combination of
- $XDG_* envars
- "standard" envars ($HOME, e.g.)
- OS/installation conventions
interact to lead to the sequence of candidate paths for the runtime
directory when the daemon starts? If such a document exists, then the
--check option blurb could avoid the need to lay it all out in gory detail
and simply say something like "The process ID of the daemon to be queried
is determined in accordance with [1]", and then add a REFERENCES subsction
to the man page and list [1] as that extant doc.
In the absence of any such extant detailed doc, I honestly don't see any way
to accurately and usefullly describe the operation of --check without including
that detail in the blurb itself, as is done below. Anything less just leaves
opportunity for confusion.
Anyway... here's what I have so far. Text in square brackets is meta-stuff.
=============================================================================
--check
Attempts to query a running PA daemon, then exits immediately with exit code
indicating the query result: Zero if the queried daemon appears to be running,
otherwise nonzero.
The process ID of the daemon to be queried is read from
$XDG_RUNTIME_DIR/pulse/pid.
If $XDG_RUNTIME_DIR is unset [??? or ???], then the pid is read from one of
$HOME/.config/pulse/xxxx-runtime/pid
$HOME/.pulse/xxxx-runtime/pid
depending on OS conventions. (xxxx denotes a hexadecimal string which
is [what? Specific to the session? seat?]) Thus, the result reported by
--check will be accurate only if both $XDG_RUNTIME_DIR and $HOME are set
as they were when the putative daemon instance was started.
If no PA daemon pid can be determined via the above paths (due to access
permissions, file or path components nonexistent, etc.) then the exit code
is nonzero.
Unless accompanied by --verbose or if an error occurs, the --check option
operates silently; only the exit code is set,
NOTE: This option is presently intended to be used only by non-root users to
query a daemon which was started by that same user. In particular, attempting
to use --check as root with $XDG_RUNTIME_DIR and/or $HOME pointing to a
non-root user's directory may permanently disable that user's ability to
communication with the daemon.
=============================================================================
