libc: Roll {l,ll,imax}div(3) manpages into just div(3)

[obiwac]

Summary

No need to have 4 separate manpages for these functions.

Sponsored by: Klara, Inc.

(will commit the small change in share/man/man3/stdckdint.3 separately)

Test Plan

Rendered version of manpage:

DIV(3)                  FreeBSD Library Functions Manual                  DIV(3)

NAME
     div, ldiv, lldiv, imaxdiv – return quotient and remainder from division

SYNOPSIS
     /* -lc */
     #include <stdlib.h>

     div_t
     div(int numer, int denom);

     ldiv_t
     ldiv(long numer, long denom);

     lldiv_t
     lldiv(long long numer, long long denom);

     #include <inttypes.h>

     imaxdiv_t
     imaxdiv(intmax_t numer, intmax_t denom);

DESCRIPTION
     The div(), ldiv(), lldiv(), and imaxdiv() functions compute the value of
     numer (the numerator) divided by denom (the denominator) and return the
     stored result in the form of the div_t, ldiv_t, lldiv_t, or imaxdiv_t
     types, respectively.  These types are structs which contain two int, long,
     long long, or intmax_t members named quot (the quotient) and rem (the
     remainder).

STANDARDS
     The div(), ldiv(), lldiv(), and imaxdiv() functions conform to ISO/IEC
     9899:2024 (“ISO C23”) and IEEE Std 1003.1-2024 (“POSIX.1”).

HISTORY
     The div() and ldiv() functions first appeared in 4.3BSD.  The lldiv() and
     imaxdiv() functions first appeared in FreeBSD 5.0.

FreeBSD 16.0-CURRENT            February 18, 2026                         DIV(3)

[obiwac]

lib/libc/stdlib/div.3

3

pulled this in from the previous lldiv(3) and imaxdiv(3) manpages.

6–10

pulled this in from the previous ldiv(3) manpage

[des]

lib/libc/stdlib/div.3

64

66

81

82–83

98–107

Should we change that to a newer version of the standard? And add POSIX?

[obiwac]

respond to des@'s review comments

[obiwac]

oops wrong diff :P

[des]

lib/libc/stdlib/div.3

106

Why not 2024?

[obiwac]

use posix 2024 as standard

[obiwac]

lib/libc/stdlib/div.3

106

not sure why I did this, probably just an oversight

[rpokala]

lib/libc/stdlib/div.3

83

These types are structs which contain two int, long, long long, or intmax_t members named quot (the quotient) and rem (the remainder).

I feel like we should include an example. Something along the lines of this, perhaps?

These types are structs which each contain two members of the appropriate type, named
.Va quot
(the quotient) and
.Va rem
(the remainder):
.Bd -literal
typedef struct {
    <type> quot, /* <type> quotient */
    <type> rem,  /* <type> remainder */
} <prefix>div_t;
.Ed

112

Should we mention when that incompatible version was replaced with the current version?

[obiwac]

lib/libc/stdlib/div.3

83

we can, this is what lldiv(3) and imaxdiv(3) had. I just thought it would be a little clunkier to have this struct for each type, but if you think having a template like your example is kosher, then we can do it like that.

112

well "different" means different to the current version, so it goes without saying it was replaced

[ziaee]

lib/libc/stdlib/div.3

38–41

I don't remember the fine details, but this is the correct syntax showed in all the reference material, and the other syntax appears to work but then when you dig in it does something weird in some corner case. I'm sorry that's not terribly satisfying.

42–44

Upstream deprecated the LIBRARY section

112

Yes, if we can say "when", that is extremely helpful for people maintaining real-world legacy installations. Great idea @rpokala!

[obiwac]

remove LIBRARY

[obiwac]

lib/libc/stdlib/div.3

38–41

we do already have a lot of manpages which use this pattern. what corner cases are you thinking of? we might want to fix the existing manpages which do this too if this ends up being a problem

112

it has had the current calling conventions since the 4.4 lite import. So as long as it has existed in FreeBSD

[des]

lib/libc/stdlib/div.3

112

1. The old three-argument ldiv() never existed in BSD, as far back as the CSRG repository goes (1979). The current ldiv() was added in 1990 after the publication of the ANSI C standard. .At v4 is AT&T Research Unix v4, released in 1973, with an installed base in the dozens. I found ldiv() in the v6 (1975) manual but it was gone by v7 (1979), which BSD was based on. I'm guessing it was removed because the continuing evolution of C, and particularly the addition of long, rendered it obsolete.

2. “calling convention” is not the correct term here, “argument list” or “prototype” would be better.

[des]

lib/libc/stdlib/div.3

112

I forgot the conclusion: we should probably just replace this sentence with the standard phrasing to indicate that ldiv() was added in .Bx 4.3.

[obiwac]

update history section

[obiwac]

lib/libc/stdlib/div.3

38–41

i have tried running mandoc -T tree on both options and they give identical trees

[des]

lib/libc/stdlib/div.3

38–41

I suspect the real argument for @ziaee's version is simply that it makes future diffs easier to read (which isn't a bad argument). I tend to agree, but it's pretty much a matter of taste.

[obiwac]

update names

[obiwac]

lib/libc/stdlib/div.3

38–41

yeah that's fair, changed