move bufsz description after appbufsz as per struct fields order

ok ratchov@

Tweak to clarify sio_stop(3) and sio_flush() description, from jmc@

Add sio_flush(3) function to stop playback immediately

The new sio_flush(3) functions works the same way as sio_stop(3),
except that it doesn't wait for play buffer to be drained. Instead,
it discards its contents and returns immediately.

man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

Clarify what sio_start() does exactly

Suggested by Erico Nogueira <ericonr@disroot.org>,
help from and ok jmc@, schwarze@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

Tweak to clarify sio_stop(3) and sio_flush() description, from jmc@

Add sio_flush(3) function to stop playback immediately

The new sio_flush(3) functions works the same way as sio_stop(3),
except that it doesn't wait for play buffer to be drained. Instead,
it discards its contents and returns immediately.

man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

Clarify what sio_start() does exactly

Suggested by Erico Nogueira <ericonr@disroot.org>,
help from and ok jmc@, schwarze@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

Add sio_flush(3) function to stop playback immediately

The new sio_flush(3) functions works the same way as sio_stop(3),
except that it doesn't wait for play buffer to be drained. Instead,
it discards its contents and returns immediately.

man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

Clarify what sio_start() does exactly

Suggested by Erico Nogueira <ericonr@disroot.org>,
help from and ok jmc@, schwarze@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

man pages: add missing commas between subordinate and main clauses

jmc@ dislikes a comma before "then" in a conditional, so leave those
untouched.

ok jmc@

Clarify what sio_start() does exactly

Suggested by Erico Nogueira <ericonr@disroot.org>,
help from and ok jmc@, schwarze@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

Clarify what sio_start() does exactly

Suggested by Erico Nogueira <ericonr@disroot.org>,
help from and ok jmc@, schwarze@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

* Add SIO_BPS() to NAME and SYNOPSIS where it is missing.
* Use .Fn rather than .Dv for macros taking arguments.
* Actually say what SIO_LE_NATIVE means.
* Add closely related APIs to SEE ALSO.
* Add missing HISTORY and AUTHORS sections.
OK ratchov@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

basic macro cleanup: .Fo for long .Fn lines, .Fa for struct fields,
avoid \*(Gt and \*(Lt, .Dv NULL, .Cm for pledge promises

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes

explain that it's ok if we get a slightly different rate than
the one we asked for, from Thomas Pfaff <tpfaff(at)tp76.info>
with tweaks from jmc@

fix bugs section: clarify that sio_start() and sio_stop() should
not be used if blocking is not desirable.

explain what ``frame'' does mean
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc

replace s/routine/function/, as other manuals do
from Thomas Pfaff <tpfaff(at)tp76.info>, thanks!
ok jmc@

oops, i messed up tim's patch; correction from Tim van der Molen

a little macro cleanup; from Tim van der Molen

stop using stderr in the library, wrap all diagnostic fprintfs
so they are visible only when the DEBUG macro is #defined
and SIO_DEBUG env. variable is set.
requested by many, discussed with jakemsr

tweak previous;

add a writable ``appbufsz'' field to the sa_par structure, containing
the program-part of the buffer size, ie the part that is subject to
underruns. Useful for apps like cdio(1) that don't have their own
rings, or to apps that have a minimum ring size constraint. Setting
the ``bufsz'' parameter becomes deprecated.
ok jakemsr

occures -> occurs;

document that sio_revents() can return POLLHUP

tweak previous;

expose a volume knob in the sndio API: add sio_setvol(3) and
sio_onvol(3) functions. The audio(4) backend tries to use the
inputs.dac, outputs.dac, outputs.output and outputs.master
controls (in this order). Add a sample file in
regress/lib/libsndio/vol/vol.c

typos; ok ratchov@ jmc@

expose the block size in the sndio API by making par->round writable
and thus remove the ugly rate <-> block-size table from
sio_setpar(3). Handle the block size negociation in aucat(1), since
it has few constrains the code is overally simpler.
ok jakemsr@, major crank suggested by deraadt@

document LIBSIO_DEBUG
ok ratchov@

rename libsa to libsndio
requested by many, "just go for it" deraadt@

move mixerctl and audioctl man pages to section 8, as these work
against root-only device nodes.

Sayt that using capabilities to negociate audio parameters (ie using
sio_getcap() function) is not recomended.

From Paul Swanson <psw at protonmail.com>, ok jmc

Move libsndio session cookie in its own $HOME/.sndio/ directory to
make libsndio easier to use with unveil(2).

"make sense" deraadt

Tweak RETURN VALUES section. Move description of sio_pollfd() and
sio_nfds() return values there and add a paragraph about sio_eof().

ok jmc ratchov

Document how to use sndio in pledged programs.

Input and OK jmc@ ratchov@ semarie@

Move sndiod man page to section 8.

suggested by deraadt, fixes from jmc, ok millert

Remove useless quoting from .Fo and .Fn function names, to prevent
development of a cargo cult in case people look at existing files
for examples. This achieves a consistent .Fo and .Fn quoting style
across the whole tree.

Kill the only instance of .Lb in our tree. It is better to not use
it at all, not even occasionally, because there is no sustainable
way (and even less any portable way) to maintain the list of library
names. Besides, without such a list, even the formatting looks bad.
OK jmc@ bentley@

say this is the "sndio" api, as we have other audio/midi apis,
makes "man -k" happier.

ok jmc, schwarze

clean up macro usage;
tweak and ok ratchov@, ok jmc@

- clarify that sio_close() stops the device first, then
frees the handle and not the opposite
- clarify that sio_close() and sio_stop() dont discard
samples in the play buffer.

suggested by Reimar Doeffinger <Reimar.Doeffinger at gmx.de>

ok jmc@

- replaces "audio stream" by "audio device", as sndio is a device
abstraction
- remove useless statements.

ok jmc@

remove FILES sections because it's incomplete, wrong and doesn't give
any useful information

shorten lines in literal blocks to avoid word wraping

use fancy .In macro for includes. from Jan Klemkow. ok jmc schwarze

explain what "default" means in sndio.7 rather than {sio,mio}_open.3,
with tweaks from jmc

Make the "default" string a valid device name that has the same effect
as NULL has. This will (hopefully) simplify ports where the user
passes the device string.

Use "unsigned int" rather than "unsigned". No object change.
suggested by deraadt@

formatting errors, found using freebsd's "igor";

mention sndiod rather than aucat when talking about the server

Remove midicat since aucat can now be used instead of midicat
with almost the same syntax (roughly an extra -M option).
Thru boxes are created with aucat, and corresponding MIDI port
names have the "aucat" prefix instead of "midithru". The old
device name will still work some time for backward compatibility.

ok deraadt

some tweaks, from Tim van der Molen

Make aucat audio and midi backends share the same code to communicate
with the server. As we're at it use the same protocol for midi and
audio. Now, both audio and midi code use the same SNDIO_DEBUG environment
variable to turn on/off DPRINTF's.

tweak previous;

make sio_onvol(3) return a integer exposing whether a volume knob
is available for the stream. As we're at it, remove macros and
functions that are neither used nor documented.

once sio_start() has been called, stream parameters cannot be
changed until after sio_stop() is called

ok ratchov@, jmc@

aucat (server):

- make the ``-m mode'' option per subdevice, allowing
subdevices to be play-only or rec-only even if the
server is full-duplex

- add ``monitoring'' mode (with ``-m mon''). This is a
record-only stream from which played streams can be
recorded (kind of ``record what you hear'').

- allow MIDI devices to be subscribed to the controlling
MIDI port of the server, ie what midicat does (with -f
option), but using the -q option.

- add flow control to the protocol, and serialize clock
ticks (sio_onmove() calls) and data chunks. This should
fix certain full-duplex programs, broken with ``magic''
block/buffer size combinations.

- enable 3 block latency which is the minimum theoretical.
Make -z and -b options correspond to device parameters.

- make sio_getcap(3) the same for aucat and sun backends,
ie return whatever is supported (``everything'' in the
aucat case, since everything is actulally supported).

aucat (player):

- enable ``-m mode'' option to select between monitoring
and recording when ``-o file'' is used.

- plug MIDI code to non-server codepath. The MIDI control
device is specified with the ``-q device'' option, as in
server mode.

- impliment lseek()'ing within files (controlled
through MIDI). Necessary to use aucat with a MIDI
sequencer.

midicat (thrubox):

- rename ``-f'' flag to ``-q'', so it has the
same name as in aucat (-f is still working)

ok jakemsr@, tweaks from jmc@

explain what sio_close() drains play buffers as if sio_close() was
called. Since sio_onmove() callback doesn't return negative deltas
anymore, slightly simplify related paragraphs.

siggested by espie@, ok jakemsr@

use const qualifier in libsndio, making it slightly more consistent
with open(2) and write(2) syscalls.
from Thomas Pfaff, jakemsr is fine with it

Currently midi capable programs can control midi hardware, but
cannot cooperate with other programs. The aim of this change is
to allow any program to send midi data to other programs as they
were midi hardware. For instance, this change should solve the
longstanding problem of using a midi sequencer with software
synthesizers. More precisely:

- new midicat(1) utility (actually hardlink to aucat(1)).
it creates software midi thru boxes, allowing programs
to send midi messages to other programs as they were
midi(4) hardware.

- new midi api in libsndio (see mio_open(3)), to access
midi(4) devices and midicat(1) sockets in a uniform way.

- new device naming scheme <service>:<unit>[.<option>],
common to audio and midi.

- new sndio(7) manual describing concepts and naming

The current audio device naming still works, but people having
scripts or configuration files containing device names could read
the sndio(7) man page and slowly start updating device names.

discussed with jakemsr@ and deraadt@, help form jmc@

describe sio_getcap(), sio_pollfd() and sio_setvol() retrurn values
spotted by Philipp Schafft

update the default socket paths, to reflect recent aucat changes