Hi,
now that s6-frontend is released, I feel allowed to ping about this. ^^
Am So, Nov 23, 2025 am 07:09:48 +0100 schrieb Hoël Bézier:
>Signed-off-by: Hoël Bézier <hoelbezier_at_riseup.net>
>---
>Here’s my take at documenting skalibs. :D I clearly have little to no experience
>in writing doc, so feel free to edit this as you see fit, or make feedback and
>have me edit it.
>
> doc/libstddjb/fmtscan.html | 82 +++++++++++++++++++++++++++++++++++++-
> 1 file changed, 80 insertions(+), 2 deletions(-)
>
>diff --git a/doc/libstddjb/fmtscan.html b/doc/libstddjb/fmtscan.html
>index 4e54e4f..dd93a5d 100644
>--- a/doc/libstddjb/fmtscan.html
>+++ b/doc/libstddjb/fmtscan.html
>_at__at_ -18,10 +18,88 _at__at_
> <a href="//skarnet.org/">skarnet.org</a>
> </p>
>
>-<h1> The <tt>skalibs/fmtscan.h</tt> header </h1>
>+<h1> Formatting and scanning functions </h1>
>
> <p>
>- TODO: write this documentation page. (Sorry!)
>+ The preferred skalibs way of converting objects to string for output is to use
>+the various <tt>*_fmt</tt> functions available in <tt>skalibs/fmtscan.h</tt>
>+and other object-specific headers. These functions take at least two parameters:
>+</p>
>+
>+<ul>
>+ <li> The target buffer into which the formatted object will be written.
>+This buffer must be large enough to hold the formatted object. </li>
>+ <li> The object that should be formatted into the buffer. </li>
>+</ul>
>+
>+<p>
>+ They return the number of bytes written into the buffer.
>+</p>
>+
>+<p>
>+ To ensure that the buffer is large enough, <tt>skalibs</tt> provides several
>+<tt>x_FMT</tt> macros corresponding to the minimum buffer size necessary for
>+formatting an object of type <em>x</em> to a string, including the terminating
>+nul byte.
>+</p>
>+
>+<p>
>+ Conversely, to scan objects from a string, skalibs provides several
>+<tt>*_scan</tt> functions. They take the same parameters as the <tt>*_fmt</tt>
>+ones, with meaning reversed. They return the number of bytes read from the
>+input buffer
>+</p>
>+
>+<h2> Examples </h2>
>+
>+<pre>
>+ uint32_t u = ... ;
>+ char buf[UINT32_FMT] ;
>+ buf[uint32_fmt(buf, u)] = 0 ;
>+</pre>
>+
>+<pre>
>+ char *buf = "123a" ;
>+ uint32_t u ;
>+ size_t p ;
>+ p = uint32_scan(buf, &u) ;
>+ // p is 3, u is 123
>+</pre>
>+
>+<h2> Functions </h2>
>+
>+<p>
>+ Formatting and scanning functions for the integer types can be found in
>+<tt>skalibs/uint16h</tt>, <tt>skalibs/uint32.h</tt> and
>+<tt>skalibs/uint64.h</tt>, those for standard unix types (such as
>+<tt>pid_t</tt> or <tt>uid_t</tt>) can be found in <tt>skalibs/types.h</tt>.
>+Other formatting functions can be found in <tt>skalibs/fmtscan.h</tt>.
>+</p>
>+
>+<p>
>+<code> size_t uint64_fmt_generic (char *s, uint64_t i, uint8_t b) </code> <br />
>+Write the representation in base <em>b</em> of integer <em>i</em> into the buffer
>+pointed to by <em>s</em>. Returns the number of bytes written.
>+</p>
>+
>+<p>
>+<code> size_t uint640_fmt_generic (char *s, uint64_t i, size_t pad, uint8_t b) </code> <br />
>+Write the representation in base <em>b</em> of integer <em>i</em> into the buffer
>+pointed to by <em>s</em>, padding if necessary with zeros to ensure the
>+written string is at least <em>pad</em> bytes long. Returns the number of
>+bytes written.
>+</p>
>+
>+<p>
>+<code> size_t uint64_scan_base (char const *s, uint64_t *i, uint8_t b) </code> <br />
>+Scan the first bytes of the buffer pointed to by <em>s</em> for an <tt>uint64_t</tt>
>+exrpessed in base <em>b</em> and write it into <em>i</em>. Returns the number of
>+bytes read.
>+<p>
>+
>+<p>
>+ The above are the most fundamental functions. Other functions are usually expressed
>+in terms of these, or have self-explanatory prototypes.
> </p>
>
> </body>
>--
>2.51.2
>
Received on Mon Feb 02 2026 - 18:25:59 CET