Welcome to little lamb

Code » limb » commit 6167454

Remove obuffers_setextralvl() for obuffers_getextra()

author Olivier Brunel
2023-04-05 17:52:14 UTC
committer Olivier Brunel
2023-05-20 18:06:35 UTC
parent 5fae3cdab0a5e5175e5f82a34649f8ce2013ff20

Remove obuffers_setextralvl() for obuffers_getextra()

Similarly remove obuffers_set{log,dbg}lvl() and introduce
obuffers_get{log,dbg}() to get a pointer to the extra buffer (to get/set
the level).

Also some minor refactoring, and add obuffers_add{log,dbg}_full() to add
the buffer specifying the level at the same time.

src/doc/obuffers.h.0.md +28 -17
src/doc/obuffers.h/obuffers_addextra.3.md +13 -7
src/doc/obuffers.h/obuffers_addlog.3.md +0 -68
src/doc/obuffers.h/obuffers_addlog_full.3.md +86 -0
src/liblimb/include/limb/obuffers.h +7 -5
src/liblimb/obuffers.h/{obuffers_adddbg.c => obuffers_adddbg_full.c} +4 -6
src/liblimb/obuffers.h/{obuffers_addlog.c => obuffers_addlog_full.c} +4 -6
src/liblimb/obuffers.h/{obuffers_setdbglvl.c => obuffers_getdbg.c} +3 -3
src/liblimb/obuffers.h/{obuffers_setextralvl.c => obuffers_getextra.c} +5 -8
src/liblimb/obuffers.h/{obuffers_setloglvl.c => obuffers_getlog.c} +3 -3

diff --git a/src/doc/obuffers.h.0.md b/src/doc/obuffers.h.0.md
index 8192f7f..dd1d50d 100644
--- a/src/doc/obuffers.h.0.md
+++ b/src/doc/obuffers.h.0.md
@@ -31,46 +31,57 @@ The following functions are defined :
 : [obuffers_addextra](3)
 :: Set up a new extra output buffer.
 
-: [obuffers_setextralvl](3)
-:: Define the output level of an extra output buffer.
+: [obuffers_getextra](3)
+:: Get a pointer to an extra output buffer.
 
 : [obuffers_remextra](3)
 :: Remove an extra output buffer.
 
-: [obuffers_addlog](3)
+
+: [obuffers_addlog_full](3)
 :: Set up a new extra buffer from the given file descriptor (e.g. to have a log
-: of all stdout/stderr messages)
+:: of all stdout/stderr messages) at the specified level.
+
+: [obuffers_addlog](3)
+:: Similar to [obuffers_addlog_full](3) with *OLVL_NORMAL*.
+
+: [obuffers_adddbg_full](3)
+:: Set up a new extra buffer from the given file descriptor (e.g. to have a
+:: debugging log of all stdout/stderr messages) at the specified level.
 
 : [obufers_adddbg](3)
-:: Similar to [obuffers_addlog](3) but this buffer will default to *OLVL_DEBUG*
+:: Similar to [obuffers_adddbg_full](3) with *OLVL_DEBUG*.
 
-: [obuffers_setloglvl](3)
-:: Define the output level of the log buffer from extra output buffers.
+: [obuffers_getlog](3)
+:: Get a pointer to the extra output buffer set up via [obuffers_addlog](3)
+:: or [obuffers_addlog_full](3).
 
-: [obuffers_setdbglvl](3)
-:: Define the output level of the debug buffer from extra output buffers.
+: [obuffers_getdbg](3)
+:: Get a pointer to the extra output buffer set up via [obuffers_adddbg](3)
+:: or [obuffers_adddbg_full](3).
 
 : [obuffers_remlog](3)
-:: Remove the log buffer from extra output buffers
+:: Remove the log buffer from extra output buffers.
 
 : [obuffers_remdbg](3)
-:: Remove the debug buffer from extra output buffers
+:: Remove the debug buffer from extra output buffers.
+
 
 : [extras_putmsg](3)
-:: Send a message to all extra output buffers
+:: Send a message to all extra output buffers.
 
 : [out_putmsg](3)
-:: Send a message to `obuffer_1` and all extra output buffers
+:: Send a message to `obuffer_1` and all extra output buffers.
 
 : [err_putmsg](3)
-:: Send a message to `obuffer_2` and all extra output buffers
+:: Send a message to `obuffer_2` and all extra output buffers.
 
 : [dbg_putmsg](3)
 :: Same as [out_putmsg](3) but prefix the message with the given function name,
-:: file name and line number. Mostly used via [dbg](3)
+:: file name and line number. Mostly used via [dbg](3).
 
 : [out_putmsgdie](3)
-:: Same as [out_putmsg](3) but terminate process execution afterwards
+:: Same as [out_putmsg](3) but terminate process execution afterwards.
 
 : [err_putmsgdie](3)
-:: Same as [err_putmsg](3) but terminate process execution afterwards
+:: Same as [err_putmsg](3) but terminate process execution afterwards.
diff --git a/src/doc/obuffers.h/obuffers_addextra.3.md b/src/doc/obuffers.h/obuffers_addextra.3.md
index f117c18..b4bc8b7 100644
--- a/src/doc/obuffers.h/obuffers_addextra.3.md
+++ b/src/doc/obuffers.h/obuffers_addextra.3.md
@@ -3,7 +3,8 @@
 
 # NAME
 
-obuffers\_addextra, obuffers\_remextra - add/remove an extra output buffer
+obuffers\_addextra, obuffers\_getextra, obuffers\_remextra - add/remove an
+extra output buffer
 
 # SYNOPSIS
 
@@ -11,7 +12,7 @@ obuffers\_addextra, obuffers\_remextra - add/remove an extra output buffer
 
 ```pre hl
 int obuffers_addextra(buffer *<em>buf</em>, u8 <em>level</em>)
-int obuffers_setextralvl(buffer *<em>buf</em>, u8 <em>level</em>)
+obuffer *obuffers_getextra(buffer *<em>buf</em>)
 int obuffers_remextra(buffer *<em>buf</em>)
 ```
 
@@ -22,16 +23,21 @@ the given buffer `buf` (which must be set up for writing), using `level` as the
 buffer's level -- meaning only sent messages with the same level or lower will
 be written into `buf`.
 
-The `obuffers_setextralvl`() function will set the output level of extra buffer
-set up using buffer `buf` to `level`.
+The `obuffers_getextra`() function returns a pointer to the extra output buffer
+set up using buffer `buf`. Note that this pointer is only valid if/until this
+extra output buffer is removed (e.g. via `obuffers_remextra`()); It is mostly
+useful to get/change the output buffer's level.
 
 The `obuffers_remextra`() function will remove the extra buffer set up using the
 buffer `buf`.
 
 # RETURN VALUE
 
-These functions returns 1 on success. Otherwise they returns 0 and sets `errno`
-to indicate the error.
+The `obuffers_addextra`() and `obuffers_remextra`() functions return 1 on
+success. Otherwise they returns 0 and sets `errno` to indicate the error.
+
+The `obuffers_getextra`() function returns a pointer to the output buffer using
+`buf`, or NULL if none was found.
 
 # ERRORS
 
@@ -40,7 +46,7 @@ The `obuffers_addextra`() function may fail if :
 : *ENOBUFS*
 :: All extra buffers are already set up.
 
-The `obuffers_setextralvl`() and `obuffers_remextra`() functions may fail if :
+The `obuffers_remextra`() function may fail if :
 
 : *ENOENT*
 :: No extra buffer found using the specified buffer
diff --git a/src/doc/obuffers.h/obuffers_addlog.3.md b/src/doc/obuffers.h/obuffers_addlog.3.md
deleted file mode 100644
index 3adddfe..0000000
--- a/src/doc/obuffers.h/obuffers_addlog.3.md
+++ /dev/null
@@ -1,68 +0,0 @@
-% limb manual
-% obuffers_addlog(3)
-
-# NAME
-
-obuffers\_addlog, obuffers\_adddbg, obuffers\_remlog, obuffers\_remdbg -
-set up/remove an extra buffer from a file descriptor
-
-# SYNOPSIS
-
-    #include <limb/obuffers.h>
-
-```pre hl
-int obuffers_addlog(int <em>fd</em>)
-int obuffers_adddbg(int <em>fd</em>)
-
-int obuffers_setloglvl(u8 <em>level</em>)
-int obuffers_setdbglvl(u8 <em>level</em>)
-
-int obuffers_remlog(void)
-int obuffers_remdbg(void)
-```
-
-# DESCRIPTION
-
-The `obuffers_addlog`() function will set up an extra buffer, using the given
-file descriptor `fd` which must be opened for writing.
-
-The `obuffers_adddbg`() is similar except that the output buffer will default to
-*OLVL_DEBUG* (instead of *OLVL_NORMAL*), thusly receiving any debug messages
-sent.
-
-The `obuffers_setloglvl`() function will set the output level to `level` for
-the extra buffer previously set up using `obuffers_addlog`().
-
-The `obuffers_setlogdbg`() function will set the output level to `level` for
-the extra buffer previously set up using `obuffers_adddbg`().
-
-The `obuffers_remlog`() function will remove the extra buffer previously set up
-using `obuffers_addlog`().
-
-The `obuffers_remdbg`() function will remove the extra buffer previously set up
-using `obuffers_adddbg`().
-
-# RETURN VALUE
-
-The `obuffers_addlog`(), `obuffers_adddbg`(), `obuffers_setloglvl`() and
-`obuffers_setdbglvl`() functions return 1 on success. Otherwise they returns 0
-and sets `errno` to indicate the error.
-
-The `obuffers_remlog`() and `obuffers_remdbg`() functions return the file
-descriptor that was used in the buffer on success. Otherwise, they return -1 and
-set `errno` to indicate the error.
-
-# ERRORS
-
-The `obuffers_addlog`() and `obuffers_adddbg`() functions may fail if :
-
-: *EADDRINUSE*
-:: A buffer was already set up using the same function
-
-They may also fail for any of the errors specified for [obuffers_addextra](3).
-
-The `obuffers_setloglvl`() and `obuffers_setdbglvl`() functions may fail for any
-of the errors specified for [obuffers_setextralvl](3).
-
-The `obuffers_remlog`() and `obuffers_remdbg`() functions may fail for any of
-the errors specified for [obuffers_remextra](3).
diff --git a/src/doc/obuffers.h/obuffers_addlog_full.3.md b/src/doc/obuffers.h/obuffers_addlog_full.3.md
new file mode 100644
index 0000000..ab89e39
--- /dev/null
+++ b/src/doc/obuffers.h/obuffers_addlog_full.3.md
@@ -0,0 +1,86 @@
+% limb manual
+% obuffers_addlog_full(3)
+
+# NAME
+
+obuffers\_addlog\_full, obuffers\_addlog, obuffers\_adddbg\_full,
+obuffers\_adddbg, obuffers\_getlog, obuffers\_getdbg, obuffers\_remlog,
+obuffers\_remdbg - set up/remove an extra buffer from a file descriptor
+
+# SYNOPSIS
+
+    #include <limb/obuffers.h>
+
+```pre hl
+int obuffers_addlog_full(int <em>fd</em>, u8 <em>level</em>)
+int obuffers_addlog(int <em>fd</em>)
+int obuffers_adddbg_full(int <em>fd</em>, u8 <em>level</em>)
+int obuffers_adddbg(int <em>fd</em>)
+
+obuffer *obuffers_getlog(void)
+obuffer *obuffers_getdbg(void)
+
+int obuffers_remlog(void)
+int obuffers_remdbg(void)
+```
+
+# DESCRIPTION
+
+The `obuffers_addlog_full`() function will set up an extra buffer, using the
+given file descriptor `fd` which must be opened for writing, with level `level`
+(i.e. only messages to the same level or less will be written to it).
+
+The `obuffers_addlog`() function is similar but with *OLVL_NORMAL*.
+
+The `obuffers_adddbg_full`() function will set up an extra buffer, using the
+given file descriptor `fd` which must be opened for writing, with level `level`
+(i.e. only messages to the same level or less will be written to it).
+
+The `obuffers_adddbg`() function is similar but with *OLVL_DEBUG*.
+
+The `obuffers_getlog`() function will return a pointer to the extra buffer
+previously set up using `obuffers_addlog_full`() or `obuffers_addlog`().
+
+The `obuffers_getdbg`() function will return a pointer to the extra buffer
+previously set up using `obuffers_adddbg_full`() or `obuffers_adddbg`().
+
+! INFO:
+! Pointers to output buffers returned by `obuffers_getlog`() and
+! `obuffers_getdbg`() are only valid until said extra buffers are removed (using
+! functions described below), and mostly intended to get/change their levels.
+
+The `obuffers_remlog`() function will remove the extra buffer previously set up
+using `obuffers_addlog`().
+
+The `obuffers_remdbg`() function will remove the extra buffer previously set up
+using `obuffers_adddbg`().
+
+! NOTE:
+! `obuffers_addlog`() and `obuffers_adddbg`() are implemented as macros to
+! `obuffers_addlog_full`() and `obuffers_adddbg_full`() respectively.
+
+# RETURN VALUE
+
+The `obuffers_addlog_full`(), `obuffers_addlog`(), `obuffers_adddbg_full`() and
+`obuffers_adddbg`() functions return 1 on success. Otherwise they returns 0
+and sets `errno` to indicate the error.
+
+The `obuffers_getlog`() and `obuffers_getdbg`() functions returns a pointer to
+the extra buffer, or NULL is none was found.
+
+The `obuffers_remlog`() and `obuffers_remdbg`() functions return the file
+descriptor that was used in the buffer on success. Otherwise, they return -1 and
+set `errno` to indicate the error.
+
+# ERRORS
+
+The `obuffers_addlog_full`(), `obuffers_addlog`(), `obuffers_adddbg_full`() and
+`obuffers_adddbg`() functions may fail if :
+
+: *EADDRINUSE*
+:: A buffer was already set up using the same function
+
+They may also fail for any of the errors specified for [obuffers_addextra](3).
+
+The `obuffers_remlog`() and `obuffers_remdbg`() functions may fail for any of
+the errors specified for [obuffers_remextra](3).
diff --git a/src/liblimb/include/limb/obuffers.h b/src/liblimb/include/limb/obuffers.h
index a0d7bb6..b8ca865 100644
--- a/src/liblimb/include/limb/obuffers.h
+++ b/src/liblimb/include/limb/obuffers.h
@@ -7,13 +7,15 @@
 #include <limb/obuffer.h>
 
 extern int obuffers_addextra(buffer *b, u8 level);
-extern int obuffers_setextralvl(buffer *b, u8 level);
+extern obuffer *obuffers_getextra(buffer *b);
 extern int obuffers_remextra(buffer *b);
 
-extern int obuffers_addlog(int fd);
-extern int obuffers_adddbg(int fd);
-extern int obuffers_setloglvl(u8 level);
-extern int obuffers_setdbglvl(u8 level);
+extern int obuffers_addlog_full(int fd, u8 level);
+#define obuffers_addlog(fd) obuffers_addlog_full(fd, OLVL_NORMAL)
+extern int obuffers_adddbg_full(int fd, u8 level);
+#define obuffers_adddbg(fd) obuffers_adddbg_full(fd, OLVL_DEBUG)
+extern obuffer *obuffers_getlog(void);
+extern obuffer *obuffers_getdbg(void);
 extern int obuffers_remlog(void);
 extern int obuffers_remdbg(void);
 
diff --git a/src/liblimb/obuffers.h/obuffers_adddbg.c b/src/liblimb/obuffers.h/obuffers_adddbg_full.c
similarity index 64%
rename from src/liblimb/obuffers.h/obuffers_adddbg.c
rename to src/liblimb/obuffers.h/obuffers_adddbg_full.c
index 13f4d36..f6d02e9 100644
--- a/src/liblimb/obuffers.h/obuffers_adddbg.c
+++ b/src/liblimb/obuffers.h/obuffers_adddbg_full.c
@@ -5,19 +5,17 @@
 #include <limb/obuffers.h>
 
 static char buf[BUFFER_OUTSIZE];
-buffer buffer_dbg_ = { .fd = -1 };
+buffer buffer_dbg_ = BUFFER_INIT(&fd_writev, -1, buf, sizeof(buf));
 
 int
-obuffers_adddbg(int fd)
+obuffers_adddbg_full(int fd, u8 level)
 {
     if (buffer_dbg_.fd >= 0)
         return (errno = EADDRINUSE, 0);
 
-    buffer_init(&buffer_dbg_, &fd_writev, fd, buf, sizeof(buf));
-    if (!obuffers_addextra(&buffer_dbg_, OLVL_DEBUG)) {
-        buffer_dbg_.fd = -1;
+    if (!obuffers_addextra(&buffer_dbg_, level))
         return 0;
-    }
 
+    buffer_dbg_.fd = fd;
     return 1;
 }
diff --git a/src/liblimb/obuffers.h/obuffers_addlog.c b/src/liblimb/obuffers.h/obuffers_addlog_full.c
similarity index 64%
rename from src/liblimb/obuffers.h/obuffers_addlog.c
rename to src/liblimb/obuffers.h/obuffers_addlog_full.c
index 97a2d7a..36e9de8 100644
--- a/src/liblimb/obuffers.h/obuffers_addlog.c
+++ b/src/liblimb/obuffers.h/obuffers_addlog_full.c
@@ -5,19 +5,17 @@
 #include <limb/obuffers.h>
 
 static char buf[BUFFER_OUTSIZE];
-buffer buffer_log_ = { .fd = -1 };
+buffer buffer_log_ = BUFFER_INIT(&fd_writev, -1, buf, sizeof(buf));
 
 int
-obuffers_addlog(int fd)
+obuffers_addlog_full(int fd, u8 level)
 {
     if (buffer_log_.fd >= 0)
         return (errno = EADDRINUSE, 0);
 
-    buffer_init(&buffer_log_, &fd_writev, fd, buf, sizeof(buf));
-    if (!obuffers_addextra(&buffer_log_, OLVL_NORMAL)) {
-        buffer_log_.fd = -1;
+    if (!obuffers_addextra(&buffer_log_, level))
         return 0;
-    }
 
+    buffer_log_.fd = fd;
     return 1;
 }
diff --git a/src/liblimb/obuffers.h/obuffers_setdbglvl.c b/src/liblimb/obuffers.h/obuffers_getdbg.c
similarity index 75%
rename from src/liblimb/obuffers.h/obuffers_setdbglvl.c
rename to src/liblimb/obuffers.h/obuffers_getdbg.c
index 1d258fb..2c3ef26 100644
--- a/src/liblimb/obuffers.h/obuffers_setdbglvl.c
+++ b/src/liblimb/obuffers.h/obuffers_getdbg.c
@@ -5,8 +5,8 @@
 
 extern buffer buffer_dbg_;
 
-int
-obuffers_setdbglvl(u8 level)
+obuffer *
+obuffers_getdbg(void)
 {
-    return obuffers_setextralvl(&buffer_dbg_, level);
+    return obuffers_getextra(&buffer_dbg_);
 }
diff --git a/src/liblimb/obuffers.h/obuffers_setextralvl.c b/src/liblimb/obuffers.h/obuffers_getextra.c
similarity index 60%
rename from src/liblimb/obuffers.h/obuffers_setextralvl.c
rename to src/liblimb/obuffers.h/obuffers_getextra.c
index 7419d4c..2c41f91 100644
--- a/src/liblimb/obuffers.h/obuffers_setextralvl.c
+++ b/src/liblimb/obuffers.h/obuffers_getextra.c
@@ -1,17 +1,14 @@
 /* This file is part of limb                           https://lila.oss/limb
  * Copyright (C) 2023 Olivier Brunel                          jjk@jjacky.com */
 /* SPDX-License-Identifier: GPL-2.0-only */
-#include <errno.h>
 #include <limb/obuffers.h>
 
-int
-obuffers_setextralvl(buffer *b, u8 level)
+obuffer *
+obuffers_getextra(buffer *b)
 {
     int n = sizeof(obuffer_extras) / sizeof(obuffer_extras[0]);
     for (int i = 0; i < n; ++i)
-        if (obuffer_extras[i].b == b) {
-            obuffer_extras[i].lvl = level;
-            return 1;
-        }
-    return (errno = ENOENT, 0);
+        if (obuffer_extras[i].b == b)
+            return &obuffer_extras[i];
+    return NULL;
 }
diff --git a/src/liblimb/obuffers.h/obuffers_setloglvl.c b/src/liblimb/obuffers.h/obuffers_getlog.c
similarity index 75%
rename from src/liblimb/obuffers.h/obuffers_setloglvl.c
rename to src/liblimb/obuffers.h/obuffers_getlog.c
index 4fc7f3f..d0ca742 100644
--- a/src/liblimb/obuffers.h/obuffers_setloglvl.c
+++ b/src/liblimb/obuffers.h/obuffers_getlog.c
@@ -5,8 +5,8 @@
 
 extern buffer buffer_log_;
 
-int
-obuffers_setloglvl(u8 level)
+obuffer *
+obuffers_getlog(void)
 {
-    return obuffers_setextralvl(&buffer_log_, level);
+    return obuffers_getextra(&buffer_log_);
 }