mixer(3): Implement mixer_get_path() function

This is better than hardcoding device paths in mixer applications.

Sponsored by:	The FreeBSD Foundation
MFC after:	1 day
Reviewed by:	dev_submerge.ch
Differential Revision:	https://reviews.freebsd.org/D45275

5 files changed, 68 insertions, 3 deletions

diff --git a/lib/libmixer/Makefile b/lib/libmixer/Makefile
index 6ca17a9d020d..3f8a4dad4a65 100644
--- a/lib/libmixer/Makefile
+++ b/lib/libmixer/Makefile
@@ -22,6 +22,7 @@ MLINKS+=	mixer.3 mixer_get_dunit.3
 MLINKS+=	mixer.3 mixer_set_dunit.3
 MLINKS+=	mixer.3 mixer_get_mode.3
 MLINKS+=	mixer.3 mixer_get_nmixers.3
+MLINKS+=	mixer.3 mixer_get_path.3
 MLINKS+=	mixer.3 MIX_ISDEV.3
 MLINKS+=	mixer.3 MIX_ISMUTE.3
 MLINKS+=	mixer.3 MIX_ISREC.3
diff --git a/lib/libmixer/Symbol.map b/lib/libmixer/Symbol.map
index f16e13d66e4c..2ce39fd058ab 100644
--- a/lib/libmixer/Symbol.map
+++ b/lib/libmixer/Symbol.map
@@ -19,3 +19,7 @@ FBSD_1.7 {
 	mixer_get_mode;
 	mixer_get_nmixers;
 };
+
+FBSD_1.8 {
+	mixer_get_path;
+};
diff --git a/lib/libmixer/mixer.3 b/lib/libmixer/mixer.3
index a3593898ed68..c8a7ee1148a8 100644
--- a/lib/libmixer/mixer.3
+++ b/lib/libmixer/mixer.3
@@ -40,6 +40,7 @@
 .Nm mixer_set_dunit ,
 .Nm mixer_get_mode ,
 .Nm mixer_get_nmixers ,
+.Nm mixer_get_path ,
 .Nm MIX_ISDEV ,
 .Nm MIX_ISMUTE ,
 .Nm MIX_ISREC ,
@@ -86,6 +87,8 @@ Mixer library (libmixer, -lmixer)
 .Ft int
 .Fn mixer_get_nmixers "void"
 .Ft int
+.Fn mixer_get_path "char * buf" "size_t size" "int unit"
+.Ft int
 .Fn MIX_ISDEV "struct mixer *m" "int devno"
 .Ft int
 .Fn MIX_ISMUTE "struct mixer *m" "int devno"
@@ -398,7 +401,21 @@ The
 function returns the maximum mixer unit number.
 Although this might sound as incorrect behavior, given that one would expect
 "nmixers" to refer to the total number of active mixers, it is more intuitive
-for applications that want to loop through all mixer devices.
+for applications that want to loop through all mixer devices (see the
+.Sx EXAMPLES
+section).
+.Pp
+The
+.Fn mixer_get_path
+function writes the path of the mixer device specified in the
+.Ar unit
+argument to the buffer specified in
+.Ar buf .
+.Ar unit
+can be either -1, in which case
+.Fn mixer_get_path
+will fetch the path of the default mixer, or between 0 and the maximum mixer
+unit.
 .Pp
 The
 .Fn MIX_ISDEV
@@ -470,9 +487,10 @@ The
 .Fn mixer_set_mute ,
 .Fn mixer_mod_recsrc ,
 .Fn mixer_get_dunut ,
-.Fn mixer_set_dunit
+.Fn mixer_set_dunit ,
+.Fn mixer_get_nmixers ,
 and
-.Fn mixer_get_nmixers
+.Fn mixer_get_path
 functions return 0 or positive values on success and -1 on failure.
 .Pp
 The
@@ -542,6 +560,22 @@ TAILQ_FOREACH(dp, &m->devs, devs) {
 
 (void)mixer_close(m);
 .Ed
+.Ss Loop through all mixer devices in the system
+.Bd -literal
+struct mixer *m;
+char buf[NAME_MAX];
+int n;
+
+if ((n = mixer_get_nmixers()) < 0)
+	errx(1, "no mixers present in the system");
+for (i = 0; i < n; i++) {
+	(void)mixer_get_path(buf, sizeof(buf), i);
+	if ((m = mixer_open(buf)) == NULL)
+		continue;
+	...
+	(void)mixer_close(m);
+}
+.Ed
 .Sh SEE ALSO
 .Xr queue 3 ,
 .Xr sysctl 3 ,
diff --git a/lib/libmixer/mixer.c b/lib/libmixer/mixer.c
index 93ace1d0c69b..4abbed9b27d3 100644
--- a/lib/libmixer/mixer.c
+++ b/lib/libmixer/mixer.c
@@ -493,3 +493,28 @@ mixer_get_nmixers(void)
 
 	return (si.nummixers);
 }
+
+/*
+ * Get the full path to a mixer device.
+ */
+int
+mixer_get_path(char *buf, size_t size, int unit)
+{
+	size_t n;
+
+	if (!(unit == -1 || (unit >= 0 && unit < mixer_get_nmixers()))) {
+		errno = EINVAL;
+		return (-1);
+	}
+	if (unit == -1)
+		n = strlcpy(buf, BASEPATH, size);
+	else
+		n = snprintf(buf, size, BASEPATH "%d", unit);
+
+	if (n >= size) {
+		errno = ENOMEM;
+		return (-1);
+	}
+
+	return (0);
+}
diff --git a/lib/libmixer/mixer.h b/lib/libmixer/mixer.h
index cb9575c5f012..80a4b5c91a82 100644
--- a/lib/libmixer/mixer.h
+++ b/lib/libmixer/mixer.h
@@ -115,6 +115,7 @@ int mixer_get_dunit(void);
 int mixer_set_dunit(struct mixer *, int);
 int mixer_get_mode(int);
 int mixer_get_nmixers(void);
+int mixer_get_path(char *, size_t, int);
 
 __END_DECLS