author | Olivier Brunel
<jjk@jjacky.com> 2023-04-05 17:52:14 UTC |
committer | Olivier Brunel
<jjk@jjacky.com> 2023-05-20 18:06:35 UTC |
parent | 5fae3cdab0a5e5175e5f82a34649f8ce2013ff20 |
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_); }