[RFC] roundup.3: New page documenting roundup(3) (was: bug in roundup(3) from <sys/param.h>)

[Alejandro Colomar]

Hi Paul,

On 1/17/23 22:53, Paul Eggert wrote:
> On 1/17/23 12:24, Alejandro Colomar wrote:
>>
>>         This  macro  produces  incorrect values when x + step would overflow or
>>         wrap around
> 
> The macro can have undefined behavior on overflow, if the result type is signed. 
> So I suggest replacing "produces incorrect values" with "has undefined behavior".
> 
> I suppose you could also document that the behavior is well-defined if the 
> result type is unsigned, but that sounds like overkill.

Indeed.  v2 below.

Cheers,

Alex

---

roundup(3)                 Library Functions Manual                 roundup(3)

NAME
        roundup - round up in steps

LIBRARY
        Standard C library (libc)

SYNOPSIS
        #include <sys/param.h>

        roundup(x, step);

DESCRIPTION
        This  macro  rounds  x to the nearest multiple of step that is not less
        than x.

        It is typically used for rounding up a pointer to align it or  increas‐
        ing a buffer to be allocated.

        This  API is not designed to be generic, and doesn’t work in some cases
        that are not important for the typical use cases described above.   See
        CAVEATS.

RETURN VALUE
        This macro returns the rounded value.

STANDARDS
        This nonstandard macro is present in glibc and some BSDs.

CAVEATS
        The arguments may be evaluated more than once.

        x should be nonnegative, and step should be positive.

        If x + step would overflow or wrap around, the behavior is undefined.

SEE ALSO
        ceil(3), floor(3), lrint(3), rint(3), lround(3), round(3)

Linux man‐pages (unreleased)        (date)                          roundup(3)

-- 
<http://www.alejandro-colomar.es/>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: OpenPGP_signature
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://sourceware.org/pipermail/libc-alpha/attachments/20230117/fb23a783/attachment.sig>