Initial import, 0.1 + pk 0.2.4-B1

1 files changed, 117 insertions, 0 deletions

diff --git a/share/man/man4/spkr.4 b/share/man/man4/spkr.4
new file mode 100644
index 0000000..b211674
--- /dev/null
+++ b/share/man/man4/spkr.4
@@ -0,0 +1,117 @@
+.TH SPKR 4
+.SH NAME
+spkr \- console speaker device driver
+.SH DESCRIPTION
+The speaker device driver allows applications to control the PC console
+speaker on an IBM-PC-compatible machine running UNIX.
+.PP
+Only one process may have this device open at any given time; open() and
+close() are used to lock and relinquish it. An attempt to open() when
+another process has the device locked will return -1 with an EBUSY error
+indication. Writes to the device are interpreted as 'play strings' in a
+simple ASCII melody notation. An ioctl() for tone generation at arbitrary
+frequencies is also supported.
+.PP
+Sound-generation does \fInot\fR monopolize the processor; in fact, the driver
+spends most of its time sleeping while the PC hardware is emitting
+tones. Other processes may emit beeps while the driver is running.
+.PP
+Applications may call ioctl() on a speaker file descriptor to control the
+speaker driver directly; definitions for the ioctl() interface are in
+sys/spkr.h. The tone_t structure used in these calls has two fields,
+specifying a frequency (in hz) and a duration (in 1/100ths of a second).
+A frequency of zero is interpreted as a rest.
+.PP
+At present there are two such ioctls. SPKRTONE accepts a pointer to a
+single tone structure as third argument and plays it. SPKRTUNE accepts a
+pointer to the first of an array of tone structures and plays them in
+continuous sequence; this array must be terminated by a final member with
+a zero duration.
+.PP
+The play-string language is modelled on the PLAY statement conventions of
+IBM BASIC 2.0. The MB, MF and X primitives of PLAY are not useful in a UNIX 
+environment and are omitted. The `octave-tracking' feature is also new.
+.PP
+There are 84 accessible notes numbered 1-83 in 7 octaves, each running from
+C to B, numbered 0-6; the scale is equal-tempered A440 and octave 3 starts
+with middle C. By default, the play function emits half-second notes with the
+last 1/16th second being `rest time'.
+.PP
+Play strings are interpreted left to right as a series of play command groups;
+letter case is ignored. Play command groups are as follows:
+.PP
+CDEFGAB -- letters A through G cause the corresponding note to be played in the
+current octave. A note letter may optionally be followed by an \fIaccidental
+sign\fR, one of # + or -; the first two of these cause it to be sharped one
+half-tone, the last causes it to be flatted one half-tone. It may also be
+followed by a time value number and by sustain dots (see below). Time values
+are interpreted as for the L command below;.
+.PP
+O <n> -- if <n> is numeric, this sets the current octave. <n> may also be one
+of 'L' or 'N' to enable or disable octave-tracking (it is disabled by default).
+When octave-tracking is on, interpretation of a pair of letter notes will
+change octaves if necessary in order to make the smallest possible jump between
+notes. Thus "olbc" will be played as "olb>c", and "olcb" as "olc<b". Octave
+locking is disabled for one letter note following by >, < and O[0123456].
+.PP
+> -- bump the current octave up one.
+.PP
+< -- drop the current octave down one.
+.PP
+N <n> -- play note n, n being 1 to 84 or 0 for a rest of current time value.
+May be followedv by sustain dots.
+.PP
+L <n> -- sets the current time value for notes. The default is L4, quarter
+notes. The lowest possible value is 1; values up to 64 are accepted. L1 sets
+whole notes, L2 sets half notes, L4 sets quarter notes, etc..
+.PP
+P <n> -- pause (rest), with <n> interpreted as for L. May be followed by
+sustain dots. May also be written '~'.
+.PP
+T <n> -- Sets the number of quarter notes per minute; default is 120. Musical
+names for common tempi are:
+
+.TS
+a a a.
+        	Tempo    	Beats Per Minute
+very slow	Larghissimo	
+        	Largo    	40-60
+         	Larghetto    	60-66
+        	Grave       	
+        	Lento       	
+        	Adagio       	66-76
+slow    	Adagietto    	
+        	Andante   	76-108
+medium   	Andantino	
+        	Moderato	108-120
+fast    	Allegretto	
+        	Allegro   	120-168
+        	Vivace    	
+        	Veloce    	
+        	Presto    	168-208
+very fast	Prestissimo	
+.TE
+.PP
+M[LNS] -- set articulation. MN (N for normal) is the default; the last 1/8th of
+the note's value is rest time. You can set ML for legato (no rest space) or
+MS (staccato) 1/4 rest space.
+.PP
+Notes (that is, CDEFGAB or N command character groups) may be followed by
+sustain dots. Each dot causes the note's value to be lengthened by one-half
+for each one. Thus, a note dotted once is held for 3/2 of its undotted value;
+dotted twice, it is held 9/4, and three times would give 27/8. 
+.PP
+Whitespace in play strings is simply skipped and may be used to separate
+melody sections.
+.SH BUGS
+Due to roundoff in the pitch tables and slop in the tone-generation and timer
+hardware (neither of which was designed for precision), neither pitch accuracy
+nor timings will be mathematically exact. There is no volume control.
+.PP
+In play strings which are very long (longer than your system's physical I/O
+blocks) note suffixes or numbers may occasionally be parsed incorrectly due
+to crossing a block boundary.
+.SH FILES
+/dev/speaker -- speaker device file
+.SH AUTHOR
+Eric S. Raymond (esr@snark.thyrsus.com) Feb 1990