From nobody Fri Apr 22 14:39:31 2022 X-Original-To: dev-commits-src-branches@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 8F884199071F; Fri, 22 Apr 2022 14:39:31 +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 4KlH9b2Zflz3rSr; Fri, 22 Apr 2022 14:39:31 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1650638371; 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=N61AfLh5/Fyz97QiqNbHJauGBp7hkr2zIwWdPp0U7RM=; b=gLAblKpPS3hh0jCsM6VEK7QTUSNfobN5ignmIPphaJzfYVSA3jP73fRswz67U3V1AV2Pzw mgTMcrcY74ufXNzr+U0GqXpaBkOJoZ+b9GU4/GPGWfUsyInVwmyvanVxBjTGfptUQsbTSI 0hOBXXhiwGsTcvFDNJtMFToupjNRS4F/zTGGpINqYujEBvaZVutPFO9mlOXp970O86zkyX WQgVMdSHYS4imu3S0Uil4inCvpL85kWNMWfQYF+Yjh9TybmgPJ8qpNagb/7TbQKqws9La+ himN/PEzjUpKqLv0EXKQ/9Ld+i8tr1BTgNnt7m1FeQXZucZJFOqQiHu+Jv3Q5w== 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 355211F20D; Fri, 22 Apr 2022 14:39:31 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 23MEdVw6014887; Fri, 22 Apr 2022 14:39:31 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 23MEdVSv014886; Fri, 22 Apr 2022 14:39:31 GMT (envelope-from git) Date: Fri, 22 Apr 2022 14:39:31 GMT Message-Id: <202204221439.23MEdVSv014886@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Gordon Bergling Subject: git: 6b642cf5c874 - releng/13.1 - time(3): Refine history in the manual page List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: gbe X-Git-Repository: src X-Git-Refname: refs/heads/releng/13.1 X-Git-Reftype: branch X-Git-Commit: 6b642cf5c8742a3c307772321e0f5e4153a0b1ad Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1650638371; 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=N61AfLh5/Fyz97QiqNbHJauGBp7hkr2zIwWdPp0U7RM=; b=LSExduH9Z7Kas6xoLYqWGotrwHYyLaM2Of/biRLjBks51CrBTTbSm1rHdH8BvRZKx0LqUE P3eAG9ItaDq45sKkjnsXc1sWjS/WZuboDJzMEW7jbdw7gjFbLS8XKZmrVeP/O9BE0/YHKf f2kd2cezzkVbvvnvN00LQ+H8kqJN8mN8z97POsj99hdT1nj5zjAGbVtcab3ejWm0Ym0ZLq qEdKeD3dXU8jaWlglyBnDmA7HS7P8npdDxZEJ5GV7O8BGLtsYC36NMzCEnhkTuTXdQlUqe 69u8zInFbyNdjiGlF5KttoNoRmtyqOylx+Cq10p+548vC/wA1ZN0aiMOjrBkeg== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1650638371; a=rsa-sha256; cv=none; b=C60oc7CVDJbkE5Uzvw8iZKCKpycAErIKI+q2KOaa/4xXV080KT0EjNtbGvFCxFf2eE6Pht P1EKSWyJNWsFZ4vWnVBRI3kpcXNVnF4TnkIWTZ+ziog0gSUDmAARa6d7pPM8W7a3PJIUrK /q233rwvorbSUyA4olEkR8Rt0z6i3JLX51oFS92fquAo9sjAZrl1qtuiSKO3zMybSeiB28 RhgSGifk92hOMW1x7CPYaH/Q0i5epLtFilbrGKC4iPi7jDCHrFfiS43cdN3e9bd8WMuS8Z 6kKaClG6zq7zQaqiz97/uvI8W+KtyHBCZqhSnIVZTzWG+o6YM0CfzS3pQKYLew== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch releng/13.1 has been updated by gbe (doc committer): URL: https://cgit.FreeBSD.org/src/commit/?id=6b642cf5c8742a3c307772321e0f5e4153a0b1ad commit 6b642cf5c8742a3c307772321e0f5e4153a0b1ad Author: Gordon Bergling AuthorDate: 2022-04-14 08:04:14 +0000 Commit: Gordon Bergling CommitDate: 2022-04-22 14:36:36 +0000 time(3): Refine history in the manual page The time() system call first appeared in Version 1 AT&T UNIX. Through the Version 3 AT&T UNIX, it returned 60 Hz ticks since an epoch that changed occasionally, because it was a 32-bit value that overflowed in a little over 2 years. In Version 4 AT&T UNIX the granularity of the return value was reduced to whole seconds, delaying the aforementioned overflow until 2038. Version 7 AT&T UNIX introduced the ftime() system call, which returned time at a millisecond level, though retained the gtime() system call (exposed as time() in userland). time() could have been implemented as a wrapper around ftime(), but that wasn't done. 4.1cBSD implemented a higher-precision time function gettimeofday() to replace ftime() and reimplemented time() in terms of that. Since FreeBSD 9 the implementation of time() uses clock_gettime(CLOCK_SECOND) instead of gettimeofday() for performance reasons. With most valuable input from Warner (imp@). Reviewed by: 0mp, jilles, imp Approved by: re (gjb) Differential Revision: https://reviews.freebsd.org/D34751 (cherry picked from commit 3e0f3678eca7c3f296b9f702992737356f1792da) --- lib/libc/gen/time.3 | 57 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 49 insertions(+), 8 deletions(-) diff --git a/lib/libc/gen/time.3 b/lib/libc/gen/time.3 index 1ff703ff572a..db7491e4c516 100644 --- a/lib/libc/gen/time.3 +++ b/lib/libc/gen/time.3 @@ -32,7 +32,7 @@ .\" @(#)time.3 8.1 (Berkeley) 6/4/93 .\" $FreeBSD$ .\" -.Dd July 18, 2003 +.Dd April 14, 2022 .Dt TIME 3 .Os .Sh NAME @@ -49,7 +49,7 @@ The .Fn time function returns the value of time in seconds since 0 hours, 0 minutes, -0 seconds, January 1, 1970, Coordinated Universal Time. +0 seconds, January 1, 1970, Coordinated Universal Time (UTC). If an error occurs, .Fn time returns the value @@ -73,12 +73,54 @@ function may fail for any of the reasons described in The .Nm function conforms to -.St -p1003.1-2001 . +.St -p1003.1-2008 . .Sh HISTORY -A +The +.Fn time +system call first appeared in +.At v1 . +Through the +.At v3 , +it returned 60 Hz ticks since an epoch that changed occasionally, because it +was a 32-bit value that overflowed in a little over 2 years. +.Pp +In +.At v4 +the granularity of the return value was reduced to whole seconds, +delaying the aforementioned overflow until 2038. +.Pp +.At v7 +introduced the +.Fn ftime +system call, which returned time at a millisecond level, +though retained the +.Fn gtime +system call (exposed as +.Fn time +in userland). +.Fn time +could have been implemented as a wrapper around +.Fn ftime , +but that wasn't done. +.Pp +.Bx 4.1c +implemented a higher-precision time function +.Fn gettimeofday +to replace +.Fn ftime +and reimplemented +.Fn time +in terms of that. +.Pp +Since +.Fx 9 +the implementation of .Fn time -function appeared in -.At v6 . +uses +.Fn clock_gettime "CLOCK_SECOND" +instead of +.Fn gettimeofday +for performance reasons. .Sh BUGS Neither .St -isoC-99 @@ -92,8 +134,7 @@ on failure; thus, it is impossible for an application to distinguish the valid time value \-1 (representing the last UTC second of 1969) from the error return value. .Pp -Systems conforming to earlier versions of the C and -.Tn POSIX +Systems conforming to earlier versions of the C and POSIX standards (including older versions of .Fx ) did not set