Re: [PATCH v3 1/2] tm.3type: describe tm_zone, tm_gmtoff

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4329 bytes --]

Hi наб,

On 7/19/22 20:38, наб wrote:
> FreeBSD timezone(3) is V7 char *timezone(int zone, int dst),
> our documentation would imply it's impossible to service this type of
> system portably
> 
> Indeed, glibc defines them both, and they make more sense for most
> use-cases than trying to use the globals
> 
> glibc cited for __USE_MISC, tm_zone invalidation is Debian 2.33-7
> POSIX cited for XSI marking is Issue 7 TC2
> CSRG CD #2 contains 4.3BSD-Tahoe with both members
> 
> We currently ship an outdated (and factually misleading) version
> of this description in ctime.3
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz> > ---
>   man3/tm.3type | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 50 insertions(+)
> 
> diff --git a/man3/tm.3type b/man3/tm.3type
> index 78e05a41a..c23fc023e 100644
> --- a/man3/tm.3type
> +++ b/man3/tm.3type
> @@ -25,8 +25,26 @@ Standard C library
>   .BR "    int         tm_yday;" \
>   "   /* Day of the year  [" 0 ", " 365 "] (Jan/01 = " 0 ") */"
>   .BR "    int         tm_isdst;" "  /* Daylight savings flag */"
> +

Use .PP.  See man-pages(7):
    Formatting conventions (general)
        Paragraphs should be separated by suitable markers  (usu‐
        ally  either .PP or .IP).  Do not separate paragraphs us‐
        ing blank lines, as this results  in  poor  rendering  in
        some output formats (such as PostScript and PDF).


> +.BR "    long        tm_gmtoff;" " /* Seconds East of UTC */"
> +.BR "    const char *tm_zone;" "   /* Timezone abbreviation */"
>   .B };
>   .fi
> +.PP
> +.RS -4
> +Feature Test Macro Requirements for glibc (see
> +.BR feature_test_macros (7)):
> +.RE
> +.PP
> +.IR tm_gmtoff ,
> +.IR tm_zone :
> +.nf
> +.\" Guarded with __USE_MISC:
> +    Since glibc 2.20:
> +        _DEFAULT_SOURCE
> +    Glibc 2.20 and earlier:
> +        _BSD_SOURCE
> +.fi
>   .SH DESCRIPTION
>   Describes time, broken down into distinct components.
>   .PP
> @@ -35,6 +53,16 @@ describes wether daylight saving time is in effect at the time described.
>   The value is positive if daylight saving time is in effect,
>   zero if it is not,
>   and negative if the information is not available.
> +.PP
> +.I tm_gmtoff
> +is the difference, in seconds, of the timezone represented by this broken-down time and UTC

Heh, as the old kernel coding style used to read,
"The limit on the length of lines is 80 columns and this is a strongly 
preferred limit."

Rationale: I can keep the font size quite big, and still have 2 
terminals in a FullHD screen side by side, with line numbers.

I can still see around 87 characters (a little more than 80),
but that line is too much for me.  If eighty-few characters really 
improve readability, I can accept that, especially for SYNOPSIS, but in 
running text, 80-char is more of a strong limit.

BTW, I just realized the SYNOPSIS moved past my screen on the terminal.
I fixed it.

> +(this is the additive inverse of
> +.BR timezone (3)).
> +.PP
> +.I tm_zone
> +is the equivalent of
> +.BR tzname (3)
> +for the timezone represented by this broken-down time.
>   .SH VERSIONS
>   In C90,
>   .I tm_sec
> @@ -48,10 +76,32 @@ in C99.
>   .SH CONFORMING TO
>   C90 and later;
>   POSIX.1-2001 and later.
> +.PP
> +.I tm_gmtoff
> +and
> +.I tm_zone
> +originate from 4.3BSD-Tahoe (where
> +.I tm_zone
> +is a
> +.IR "char *" ).
>   .SH NOTES
>   .I tm_sec
>   can represent a leap second with the value
>   .BR 60 .
> +.PP
> +.BR timezone (3),
> +as a variable, is an XSI extension: some systems provide the V7-compatible
> +.\" FreeBSD
> +.BR timezone ()

I've been thinking about if we should put there a section number.
I think we should.  Actually, timezone(3) documents the function in NOTES.

Cheers,

Alex

> +function.
> +The
> +.I tm_gmtoff
> +field provides an alternative (with the opposite sign) for those systems.
> +.PP
> +.I tm_zone
> +points to static storage and may be overriden on subsequent calls to
> +.BR localtime (3)
> +and similar functions (however, this never happens under glibc).
>   .SH SEE ALSO
>   .BR ctime (3),
>   .BR strftime (3),

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]