Use a local implementation of strptime() instead of broken OS ones

[disorder] / doc / disorder.1.in

diff --git a/doc/disorder.1.in b/doc/disorder.1.in
index a05ca8c1b9b58637689507e75e144aa992f51412..784083c6a9618ce085964511e41cf6658dbafaae 100644 (file)
--- a/doc/disorder.1.in
+++ b/doc/disorder.1.in
@@ -1,20 +1,18 @@
 .\"
 .\"

-.\" Copyright (C) 2004, 2005, 2006 Richard Kettlewell
+.\" Copyright (C) 2004-2008 Richard Kettlewell

 .\"
 .\"

-.\" This program is free software; you can redistribute it and/or modify
+.\" This program is free software: you can redistribute it and/or modify

 .\" it under the terms of the GNU General Public License as published by
 .\" it under the terms of the GNU General Public License as published by

-.\" the Free Software Foundation; either version 2 of the License, or
+.\" the Free Software Foundation, either version 3 of the License, or

 .\" (at your option) any later version.
 .\" (at your option) any later version.

-.\"
-.\" This program is distributed in the hope that it will be useful, but
-.\" WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-.\" General Public License for more details.
-.\"
+.\" 
+.\" This program is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\" 

 .\" You should have received a copy of the GNU General Public License
 .\" You should have received a copy of the GNU General Public License

-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
-.\" USA
+.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.

 .\"
 .TH disorder 1
 .SH NAME
 .\"
 .TH disorder 1
 .SH NAME


@@ -22,16 +20,9 @@ disorder \- DisOrder jukebox client
 .SH SYNOPSIS
 .B disorder
 .RI [ OPTIONS ]
 .SH SYNOPSIS
 .B disorder
 .RI [ OPTIONS ]

-.RB [ -- ]
+.RB [ \-\- ]

 .RI [ COMMANDS ...]
 .RI [ COMMANDS ...]

-.br
-.B disorder
-.B --length
-.RI [ OPTIONS ]
-.RB [ -- ]
-.IR PATH ...

 .SH DESCRIPTION
 .SH DESCRIPTION

-Without the \fB--length\fR option,

 .B disorder
 is used to query the \fBdisorderd\fR(8) daemon from the command line.
 It may be used to request tracks, scratch tracks, query the current
 .B disorder
 is used to query the \fBdisorderd\fR(8) daemon from the command line.
 It may be used to request tracks, scratch tracks, query the current


@@ -39,40 +30,69 @@ state, etc, and by an administrator to shutdown or reconfigure the
 daemon.
 .PP
 If no commands are specified then \fBdisorder\fR connects to the
 daemon.
 .PP
 If no commands are specified then \fBdisorder\fR connects to the

-daemon and then immediately disconnects.  This can be used to test
-whether the daemon is running.  Otherwise, it executes the commands
-specified.
+daemon and then immediately disconnects.
+This can be used to test whether the daemon is running.
+Otherwise, it executes the commands specified.
+.PP
+This man page documents the command-line client.
+See \fBdisorderd\fR (8) for information about the server process
+and \fBdisorder_config\fR (5) for documentation of the configuration file.

 .SH OPTIONS
 .TP
 .SH OPTIONS
 .TP

-.B --config \fIPATH\fR, \fB-c \fIPATH
-Set the configuration file.  The default is
+.B \-\-config \fIPATH\fR, \fB\-c \fIPATH
+Set the configuration file.
+The default is

 .IR pkgconfdir/config .
 .TP
 .IR pkgconfdir/config .
 .TP

-.B --debug\fR, \fB-d
+.B \-\-debug\fR, \fB\-d

 Enable debugging.
 .TP
 Enable debugging.
 .TP

-.B --help\fR, \fB-h
+.B \-\-help\fR, \fB\-h

 Display a usage message.
 .TP
 Display a usage message.
 .TP

-.B --length\fR, \fB-L
-Calculate the length in seconds of the files specified using the tracklength
-plugin.
-.TP
-.B --version\fR, \fB-V
+.B \-\-version\fR, \fB\-V

 Display version number.
 .TP
 Display version number.
 .TP

-.B --help-commands\fR, \fB-H
+.B \-\-help\-commands\fR, \fB\-H

 List all known commands.
 .SH COMMANDS
 .TP
 List all known commands.
 .SH COMMANDS
 .TP

+.B adduser \fIUSERNAME PASSWORD\fR [\fIRIGHTS\fR]
+Create a new user.
+If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
+setting from the server's configuration file applies.
+.TP
+.B adopt \fIID\fR
+Adopts track \fIID\fR (in the queue).
+The track will show up as submitted by the calling user.
+.TP
+.B authorize \fIUSERNAME\fR [\fIRIGHTS\fR]
+Create user \fIUSERNAME\fR with a random password.
+User \fIUSERNAME\fR must be a UNIX login user (not just any old string).
+If \fIRIGHTS\fR is not specified then the \fBdefault_rights\fR
+setting from the server's configuration file applies.
+.IP
+\fI~USERNAME/.disorder/passwd\fR is created with the password in it, so the new
+user should be able to log in immediately.
+.IP
+If writing the \fIpasswd\fR file fails then the user will already have been
+created in DisOrder's user database.
+Use \fBdisorder deluser\fR to remove them before trying again.
+.TP
+.B deluser \fIUSERNAME\fR
+Delete a user.
+.TP

 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the directories in \fIDIRECTORY\fR.
 .IP
 .B dirs \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the directories in \fIDIRECTORY\fR.
 .IP

-An optional regexp may be specified, marked with an initial \fB~\fR.  Only
-directories with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only directories with a basename matching the regexp will be returned.

 .TP
 .B disable
 .TP
 .B disable

-Disables playing after the current track finishes.
+Disable playing after the current track finishes.
+.TP
+.B edituser \fIUSERNAME PROPERTY VALUE
+Set some property of a user.

 .TP
 .B enable
 (Re-)enable playing.
 .TP
 .B enable
 (Re-)enable playing.


@@ -80,23 +100,25 @@ Disables playing after the current track finishes.
 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the files in \fIDIRECTORY\fR.
 .IP
 .B files \fIDIRECTORY\fR [\fB~\fIREGEXP\fR]
 List all the files in \fIDIRECTORY\fR.
 .IP

-An optional regexp may be specified, marked with an initial \fB~\fR.  Only
-files with a basename matching the regexp will be returned.
+An optional regexp may be specified, marked with an initial \fB~\fR.
+Only files with a basename matching the regexp will be returned.

 .TP
 .B get \fITRACK\fR \fIKEY\fR
 Display the preference \fIKEY\fR for \fITRACK\fR.
 .TP
 .B get \fITRACK\fR \fIKEY\fR
 Display the preference \fIKEY\fR for \fITRACK\fR.

+See \fBdisorder_preferences\fR (5).

 .TP
 .TP

-.B get-global \fIKEY\fR
+.B get\-global \fIKEY\fR

 Get a global preference.
 Get a global preference.

+See \fBdisorder_preferences\fR (5).

 .TP
 .TP

-.B get-volume
-Displays the current volume settings.
+.B get\-volume
+Display the current volume settings.

 .TP
 .B length \fITRACK\fR
 .TP
 .B length \fITRACK\fR

-Reports the length of \fITRACK\fR in seconds.
+Display the length of \fITRACK\fR in seconds.

 .TP
 .B log
 .TP
 .B log

-Writes event log messages to standard output, until the server is terminated.
+Write event log messages to standard output, until the server is terminated.

 See \fBdisorder_protocol\fR (5) for details of the output syntax.
 .TP
 .B move \fITRACK\fR \fIDELTA\fR
 See \fBdisorder_protocol\fR (5) for details of the output syntax.
 .TP
 .B move \fITRACK\fR \fIDELTA\fR


@@ -104,22 +126,25 @@ Move
 .I TRACK
 by
 .I DELTA
 .I TRACK
 by
 .I DELTA

-within the queue.  Positive values move towards the head of the queue, negative
+within the queue.
+Positive values move towards the head of the queue, negative

 values towards the tail.
 .IP
 Note that if you specify a negative value then the
 values towards the tail.
 .IP
 Note that if you specify a negative value then the

-.B --
+.B \-\-

 option separate (before all commands) becomes mandatory, as otherwise the
 negative value is misinterpreted an an option.
 .TP
 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
 Get a track name part.
 .IP
 option separate (before all commands) becomes mandatory, as otherwise the
 negative value is misinterpreted an an option.
 .TP
 .B part \fITRACK\fR \fICONTEXT\fI \fIPART\fR
 Get a track name part.
 .IP

-\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.  \fBpart\fR is the
-part of the name desired, typically \fBartist\fR, \fBalbum\fR or \fBtitle\fR.
+\fICONTEXT\fR should be either \fBsort\fR or \fBdisplay\fR.
+\fBpart\fR is the part of the name desired, typically \fBartist\fR,
+\fBalbum\fR or \fBtitle\fR.

 .TP
 .B pause
 .TP
 .B pause

-Pause the current track.  (Note that not all players support pausing.)
+Pause the current track.
+(Note that not all players support pausing.)

 .TP
 .B play \fITRACKS\fR...
 Add \fITRACKS\fR to the end of the queue.
 .TP
 .B play \fITRACKS\fR...
 Add \fITRACKS\fR to the end of the queue.


@@ -129,58 +154,123 @@ Report the currently playing track.
 .TP
 .B prefs \fITRACK\fR
 Display all the preferences for \fITRACK\fR.
 .TP
 .B prefs \fITRACK\fR
 Display all the preferences for \fITRACK\fR.

+See \fBdisorder_preferences\fR (5).

 .TP
 .B queue
 .TP
 .B queue

-List the current queue.  The first entry in the list is the next track to play.
+List the current queue.
+The first entry in the list is the next track to play.

 .TP
 .TP

-.B random-disable
+.B random\-disable

 Disable random play.
 .TP
 Disable random play.
 .TP

-.B random-enable
+.B random\-enable

 Enable random play.
 .TP
 .B recent
 Enable random play.
 .TP
 .B recent

-List recently played tracks.  The first entry is the oldest track, the last
-entry is the most recently played one.
+List recently played tracks.
+The first entry is the oldest track, the last entry is the most
+recently played one.
+.TP
+.B reconfigure
+Make the daemon reload its configuration file.

 .TP
 .B remove \fITRACK\fR
 Remove a track from the queue.
 .TP
 .TP
 .B remove \fITRACK\fR
 Remove a track from the queue.
 .TP

+.B rescan
+Rescan the filesystem for new tracks.
+There is an automatic daily rescan but if you've just added some tracks
+and want them to show up immediately, use this command.
+.TP

 .B resolve \fITRACK\fR
 Resolve aliases for \fITRACK\fR and print out the real track name.
 .TP
 .B resume
 Resume the current track after a pause.
 .TP
 .B resolve \fITRACK\fR
 Resolve aliases for \fITRACK\fR and print out the real track name.
 .TP
 .B resume
 Resume the current track after a pause.
 .TP

-.B rtp-address
+.B rtp\-address

 Report the RTP brodcast address used by the server (if any).
 .TP
 Report the RTP brodcast address used by the server (if any).
 .TP

+.B schedule-del \fIEVENT\fR
+Delete a scheduled event.
+.TP
+.B schedule-list
+List scheduled events.
+Each line contains the ID, a timestamp, 'N' or 'J' for normal or junk priority,
+the user, the action and action-specific data.
+.TP
+.B schedule-play \fIWHEN PRIORITY TRACK\fI
+Play \fITRACK\fR at time \fIWHEN\fR.
+Various time/date formats are supported depending on locale but the following
+three will always work:
+.RS
+.RS
+.TP
+.B "YYYY-MM-DD HH:MM:SS"
+.TP
+.B "HH:MM:SS"
+.TP
+.B "HH:MM"
+.RE
+.RE
+.IP
+\fIPRIORITY\fR should be \fBjunk\fR or \fBnormal\fR.
+This determines how the event is handled if it becomes due when the server is
+down.
+Junk events are just discarded in this case, while normal events will be
+executed when the server comes back up, even if this is much later.
+.TP
+.B schedule-set-global \fIWHEN PRIORITY NAME VALUE\fI
+Set global preference \fINAME\fR to \fIVALUE\fR at time \fIWHEN\fR.
+.TP
+.B schedule-unset-global \fIWHEN PRIORITY NAME\fI
+Unset global preference \fINAME\fR at time \fIWHEN\fR.
+.TP

 .B scratch
 Scratch the currently playing track.
 .TP
 .B scratch
 Scratch the currently playing track.
 .TP

-.B scratch-id \fIID\fR
+.B scratch\-id \fIID\fR

 Scratch the currently playing track, provided it has the given ID.
 .TP
 .B search \fITERMS\fR
 Scratch the currently playing track, provided it has the given ID.
 .TP
 .B search \fITERMS\fR

-Search for tracks containing all of the listed terms.  The terms are
-separated by spaces and form a single argument, so must be quoted,
-for example:
+Search for tracks containing all of the listed terms.
+The terms are separated by spaces and form a single argument,
+so must be quoted, for example:

 .IP
 .B "disorder search 'bowie china'"
 .IP
 You can limit the search to tracks with a particular tag, too, using the
 .IP
 .B "disorder search 'bowie china'"
 .IP
 You can limit the search to tracks with a particular tag, too, using the

-\fBtag:\fR modifier.  For example:
+\fBtag:\fR modifier.
+For example:

 .IP
 .B "disorder search 'love tag:depressing'"
 .TP
 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.
 .IP
 .B "disorder search 'love tag:depressing'"
 .TP
 .B set \fITRACK\fR \fIKEY\fR \fIVALUE\fR
 Set the preference \fIKEY\fR for \fITRACK\fR to \fIVALUE\fR.

+See \fBdisorder_preferences\fR (5).

 .TP
 .TP

-.B set-global \fIKEY\fR \fIVALUE\fR
+.B set\-global \fIKEY\fR \fIVALUE\fR

 Set a global preference.
 Set a global preference.

+See \fBdisorder_preferences\fR (5).
+.TP
+.B set\-volume \fBLEFT\fR \fBRIGHT\fR
+Set the volume.

 .TP
 .TP

-.B set-volume \fBLEFT\fR \fBRIGHT\fR
-Sets the volume.
+.B setup\-guest \fR[\fB\-\-no\-online\-registration\fR]
+Create the "guest" user for use by the web interface.
+This user will have no password and will only have the "read" and
+"register" rights, the latter allowing new users to automatically
+register themselves via the web interface.
+.IP
+With the option \fB\-\-no-online\-registration\fR, the "register" right is
+suppressed and users must be manually created by an administrator.
+.IP
+If online registration is desired then \fBmail_sender\fR must be set in the
+configuration file.
+See \fBdisorder_config\fR(5).
+.TP
+.B shutdown
+Shut down the daemon.

 .TP
 .B stats
 List server statistics.
 .TP
 .B stats
 List server statistics.


@@ -190,9 +280,17 @@ List known tags.
 .TP
 .B unset \fITRACK\fR \fIKEY\fR
 Unset the preference \fIKEY\fR for \fITRACK\fR.
 .TP
 .B unset \fITRACK\fR \fIKEY\fR
 Unset the preference \fIKEY\fR for \fITRACK\fR.

+See \fBdisorder_preferences\fR (5).

 .TP
 .TP

-.B unset-global \fIKEY\fR
+.B unset\-global \fIKEY\fR

 Unset the global preference \fIKEY\fR.
 Unset the global preference \fIKEY\fR.

+See \fBdisorder_preferences\fR (5).
+.TP
+.B userinfo \fIUSERNAME PROPERTY
+Get some property of a user.
+.TP
+.B users
+List known users.

 .TP
 .B version
 Report the daemon's version number.
 .TP
 .B version
 Report the daemon's version number.


@@ -201,92 +299,32 @@ For
 .B move
 and
 .BR remove ,
 .B move
 and
 .BR remove ,

-tracks may be specified by name or by ID.  If you use the name and a track
-appears twice in the queue it is undefined which is affected.
-.SS "Privileged Commands"
-These commands are only available to privileged users.
-.TP
-.B become \fIUSER\fR
-Become another user.
-.TP
-.B reconfigure
-Make the daemon reload its configuration file.
-.TP
-.B rescan
-Rescan the filesystem for new tracks.  There is an automatic daily rescan but
-if you've just added some tracks and want them to show up immediately, use this
-command.
-.TP
-.B shutdown
-Shut down the daemon.
-.SH PREFERENCES
-Currently the following preferences are supported.  Some are expected
-to be set by users, others updated automatically by plugins.
-.TP
-.B pick_at_random
-If this preference is present and set to "0" then the track will not
-be picked for random play.  Otherwise it may be.
-.TP
-.B played
-A decimal integer giving the number times the track was played.  This
-includes tracks that are scratched or were picked at random.
-.TP
-.B played_time
-The last time the track was played, as a \fBtime_t\fR converted to a
-decimal integer.
-.TP
-.B scratched
-The number of times the track has been scratched.
-.TP
-.B requested
-A decimal integer giving the number of times the track was requested.
-(Tracks that are removed before being played are not counted.)
-.TP
-.B tags
-Tags that apply to this track, separated by commas.  Tags can contain any
-printing character except comma.  Leading and trailing spaces are not
-significant but internal spaces are.
-.IP
-Using the
-.B required-tags
-and
-.B prohibited-tags
-global preferences, it is possible to limit the tracks that will be selected at
-random.
-.TP
-.B trackname_\fICONTEXT\fB_\fIPART\fR
-These preferences can be used to override the filename parsing rules
-to find a track name part.  For backwards compatibility,
-\fBtrackname_\fIPART\fR will be used if the full version
-is not present.
-.TP
-.B unscratched
-The number of times the track has been played to completion without
-being scratched.
-.SH "Superuser Commands"
-These commands will (generally) only work for root, who must be a privileged
-user.
-.TP
-.B authorize \fIUSER\fR
-Chooses a password for \fIUSER\fR and adds it to \fIconfig.private\fR.  Also
-creates an appropriate \fIconfig.USER\fR, be owned by the user.
-.IP
-If at least one \fBauthorize\fR command succeeds then the server is
-automatically told to re-read its configuration.
+tracks may be specified by name or by ID.
+If you use the name and a track appears twice in the queue it is
+undefined which is affected.

 .SH NOTES
 .B disorder
 .SH NOTES
 .B disorder

-is locale-aware.  If you do not set the locale correctly then it may
-not handle non-ASCII data properly.
+is locale-aware.
+If you do not set the locale correctly then it may not handle non-ASCII
+data properly.
+.PP
+The client determines which user to attempt to authenticate as by examining the
+current UID.
+This can be overridden in a per-user configuration file, see
+\fBdisorder_config\fR(5).

 .PP
 .PP

-The client determines which user to attempt to authenticate as by
-examining the current UID.
+See \fBdisorder_protocol\fR(5) for the rights required to run each command.
+(For instance, \fBshutdown\fR requires the \fBadmin\fR right, which most users
+would not normally have.)

 .PP
 This program is not intended to run in a setuid environment.
 .PP
 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the
 .PP
 This program is not intended to run in a setuid environment.
 .PP
 The regexp syntax used by the \fBfiles\fR and \fBdirs\fR commands use the

-syntax described in \fBpcrepattern\fR(3).  Matching is case-independent.  It is
-strongly recommended that you quote regexps, since they often contain
-characters treated specially by the shell.  For example:
+syntax described in \fBpcrepattern\fR(3).
+Matching is case-independent.
+It is strongly recommended that you quote regexps, since they often
+contain characters treated specially by the shell.
+For example:

 .PP
 .B "disorder dirs /Music ~'^(?!the [^t])t'"
 .SH TROUBLESHOOTING
 .PP
 .B "disorder dirs /Music ~'^(?!the [^t])t'"
 .SH TROUBLESHOOTING


@@ -304,8 +342,8 @@ though this depends on local configuration.
 .B .
 Is the track in a known format?  Have a look at
 .I pkgconfdir/config
 .B .
 Is the track in a known format?  Have a look at
 .I pkgconfdir/config

-for the formats recognized by the local installation.  The filename matching is
-case-sensitive.
+for the formats recognized by the local installation.
+The filename matching is case-sensitive.

 .TP
 .B .
 Do permissions on the track allow the server to read it?
 .TP
 .B .
 Do permissions on the track allow the server to read it?


@@ -315,22 +353,22 @@ Do the permissions on the containing directories allow the server to read and
 execute them?
 .PP
 The user the server runs as is determined by the \fBuser\fR directive in the
 execute them?
 .PP
 The user the server runs as is determined by the \fBuser\fR directive in the

-configuration file.  The README recommends using \fBjukebox\fR for this purpose
-but it could be different locally.
+configuration file.
+The README recommends using \fBjukebox\fR for this purpose but it could
+be different locally.

 .SH ENVIRONMENT
 .TP
 .SH ENVIRONMENT
 .TP

-.B LOGNAME
-The default username.
-.TP

 .B HOME
 The user's home directory.
 .TP
 .B LC_ALL\fR, \fBLANG\fR, etc
 .B HOME
 The user's home directory.
 .TP
 .B LC_ALL\fR, \fBLANG\fR, etc

-Current locale.  See \fBlocale\fR(7).
+Current locale.
+See \fBlocale\fR(7).

 .SH FILES
 .TP
 .I pkgconfdir/config
 .SH FILES
 .TP
 .I pkgconfdir/config

-Global configuration file.  See \fBdisorder_config\fR(5).
+Global configuration file.
+See \fBdisorder_config\fR(5).

 .TP
 .I ~/.disorder/passwd
 Per-user password file
 .TP
 .I ~/.disorder/passwd
 Per-user password file


@@ -339,7 +377,8 @@ Per-user password file
 Communication socket for \fBdisorder\fR(1).
 .SH "SEE ALSO"
 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),
 Communication socket for \fBdisorder\fR(1).
 .SH "SEE ALSO"
 \fBdisorderd\fR(8), \fBdisorder_config\fR(5), \fBsyslog\fR(3), \fBtime\fR(2),

-\fBpcrepattern\fR(3), \fBdisobedience\fR(1)
+\fBpcrepattern\fR(3), \fBdisobedience\fR(1), \fBdisorder.cgi\fR(8),
+\fBdisorder_preferences\fR(5)

 .PP
 "\fBpydoc disorder\fR" for the Python API documentation.
 .\" Local Variables:
 .PP
 "\fBpydoc disorder\fR" for the Python API documentation.
 .\" Local Variables: