From nobody Wed Mar 27 11:26:17 2024 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4V4PWG1FLhz5FHyb; Wed, 27 Mar 2024 11:26:18 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4V4PWF6dBwz4bhj; Wed, 27 Mar 2024 11:26:17 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1711538777; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SRFhytp2W4E96c1FWqFp8bAHLlKSnHc1XgF7P9aY8kY=; b=NsMyM2tJSKhvJgNChgzvLNgINrFaGn0YunLvy6VvVcpGila6ByjeycUpGSOThaCAZAs6xq b6crxX3bz+XxGohs99qhixd3jg5x2shg5Z8ebFTser3560A5yebAthyWxysyslFO/vjKo0 kgIGrY1ajNrPTJY9QjWFJ08Bx9ut9H1zpYPQtf5m12NcEfilTLhUFsQvO82rm2DaGRnEI1 aAGT//g8+ITpqdVB8tTS84+4ZXtTzF4YPledN74SiY3KVGp/JqB8ly8ZKGZeKDGbXviciA h9qXJRT2SslYPJCVh2hzkSiqK/dCencLqZXExOJ6NP35FJq6AW6Kx24t6CGkqQ== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1711538777; a=rsa-sha256; cv=none; b=G7nO80ZnOmSR2xfNHHMCW0TH1yLn6rJUZIM18ubIRIU37rcoAnJbyAhF83uEb/2UMkRPfh FjigBzl66frcTWJxQ/9qZ/xDaH14VuIPdLE8nloKg6BH7u5t4KjM9GpEbpJlNx/bh3NnXu NFpI+p5f2TDTIy2ICOqQr5t9et/V7d3I6iiSXdjrtLexXE3sN5VxX2vAU9Jr92qkxSSuHG rEDPEBNiOm496D2+rPmM6YBUpqqy+e56YP2g+7/HQ2SVpVg0ONtcic/PiM1wNxxY9fL6he 8FfQVqDPgDSQnQXKkNjvK6QqxUtsbH8EeZgvJcXeJeJSo1mrmF1sH3i6Bt7ioQ== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1711538777; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=SRFhytp2W4E96c1FWqFp8bAHLlKSnHc1XgF7P9aY8kY=; b=K08K4nDhPp2IhigUjoANMZs23QHzDLCGh1W7eIcmyJsGjUKtQFyepAWhfgD8s8HAIjuAWt 8AB4mltuYQlPeqS2j7w0265ewrv563Xvmmm2DEWplJu1ocTFtfuumzLwpgdoul+c36u3o8 uLaRe/xNVD8h1cBeyL0yZ20UxBJ1gEnCPvAoHlkPHlveHb62nQ+BHnjUlCryd1eCb9jJX+ DvKpZcKAOvhzu+f5azDotyGPTE3epKvLHH/AtBsWCN9aG3OTkUYZ3LdnhnOsAgADQj5WDE wEr71fooOJ9ZplOwH9/86YuZLetlGP5WgHzZ0y1zitcQXMdLJrmnjX3vt5UvaQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4V4PWF6DrczhWw; Wed, 27 Mar 2024 11:26:17 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 42RBQHOB003739; Wed, 27 Mar 2024 11:26:17 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 42RBQHcA003736; Wed, 27 Mar 2024 11:26:17 GMT (envelope-from git) Date: Wed, 27 Mar 2024 11:26:17 GMT Message-Id: <202403271126.42RBQHcA003736@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Dag-Erling =?utf-8?Q?Sm=C3=B8rgrav?= Subject: git: 7534109d13a6 - main - libc: Improve description of mktime() / timegm(). List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: des X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 7534109d13a6cdb22e78d9d4c0a0cd5efd323c45 Auto-Submitted: auto-generated The branch main has been updated by des: URL: https://cgit.FreeBSD.org/src/commit/?id=7534109d13a6cdb22e78d9d4c0a0cd5efd323c45 commit 7534109d13a6cdb22e78d9d4c0a0cd5efd323c45 Author: Dag-Erling Smørgrav AuthorDate: 2024-03-27 10:03:37 +0000 Commit: Dag-Erling Smørgrav CommitDate: 2024-03-27 10:03:37 +0000 libc: Improve description of mktime() / timegm(). * Mention that mktime() and timegm() set errno on failure. * Correctly determining whether mktime() / timegm() succeeded with arbitrary input (where -1 can be a valid result) is non-trivial. Document the recommended procedure. PR: 277863 MFC after: 1 week Reviewed by: pauamma_gundo.com, gbe Differential Revision: https://reviews.freebsd.org/D44503 --- lib/libc/stdtime/ctime.3 | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/lib/libc/stdtime/ctime.3 b/lib/libc/stdtime/ctime.3 index 698a63cfa73d..96b7f775535a 100644 --- a/lib/libc/stdtime/ctime.3 +++ b/lib/libc/stdtime/ctime.3 @@ -27,7 +27,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd April 20, 2023 +.Dd March 26, 2024 .Dt CTIME 3 .Os .Sh NAME @@ -241,7 +241,21 @@ The .Fn mktime function returns the specified calendar time; if the calendar time cannot be -represented, it returns \-1; +represented, it returns \-1 and sets +.Xr errno 3 +to an appropriate value. +.Pp +Note that \-1 is a valid result (representing one second before +midnight UTC on the evening of 31 December 1969), so this cannot be +relied upon to indicate success or failure; instead, +.Fa tm_wday +and / or +.Fa tm_yday +should be set to an out-of-bounds value (e.g. \-1) prior to calling +.Fn mktime +or +.Fn timegm +and checked after the call. .Pp The .Fn difftime