git: c32f8e613e57 - stable/14 - Document that gettimeofday() is obsolescent

The branch stable/14 has been updated by 0mp:

URL: https://cgit.FreeBSD.org/src/commit/?id=c32f8e613e5795239359ca53f7a4dfe30ed1933a

commit c32f8e613e5795239359ca53f7a4dfe30ed1933a
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2024-04-24 11:31:54 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2024-05-04 13:04:47 +0000

    Document that gettimeofday() is obsolescent
    
    Reported by:    kaktus
    Reviewed by:    kaktus, pstef
    MFC after:      3 days
    Differential Revision:  https://reviews.freebsd.org/D23942
    
    (cherry picked from commit 4395d3ced5cfa46df400b5bb9996f9d74476997e)
---
 lib/libc/sys/gettimeofday.2 | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/lib/libc/sys/gettimeofday.2 b/lib/libc/sys/gettimeofday.2
index a27aecba3fc7..27149dcbeb1d 100644
--- a/lib/libc/sys/gettimeofday.2
+++ b/lib/libc/sys/gettimeofday.2
@@ -27,7 +27,7 @@
 .\"
 .\"     @(#)gettimeofday.2	8.2 (Berkeley) 5/26/95
 .\"
-.Dd May 13, 2021
+.Dd April 24, 2024
 .Dt GETTIMEOFDAY 2
 .Os
 .Sh NAME
@@ -43,6 +43,17 @@
 .Ft int
 .Fn settimeofday "const struct timeval *tp" "const struct timezone *tzp"
 .Sh DESCRIPTION
+.Em Note :
+The
+.Nm gettimeofday
+function
+.Po but not
+.Nm settimeofday Pc
+is obsolescent.
+See the
+.Sx STANDARDS
+section for more details.
+.Pp
 The system's notion of the current Greenwich time and the current time
 zone is obtained with the
 .Fn gettimeofday
@@ -123,6 +134,18 @@ A user other than the super-user attempted to set the time.
 .Xr ctime 3 ,
 .Xr timeradd 3 ,
 .Xr clocks 7
+.Sh STANDARDS
+The
+.Nm gettimeofday
+function is considered obsolescent and its usage discouraged by
+.\" XXX: This should be replaced in the future when an appropriate argument to
+.\" the St macro is available: -p1003.1-2017
+.No IEEE Std 1003.1-2008, 2017 Edition (\\(LqPOSIX.1\\(Rq) .
+Application should use the
+.Xr clock_gettime 2
+function instead as
+.Nm gettimeofday
+might be removed in the future.
 .Sh HISTORY
 The
 .Fn gettimeofday