Re: git: 4395d3ced5cf - main - Document that gettimeofday() is obsolescent

On Thu, Apr 25, 2024 at 09:44:00AM +0000, Mateusz Piotrowski wrote:
> The branch main has been updated by 0mp:
> 
> URL: https://cgit.FreeBSD.org/src/commit/?id=4395d3ced5cfa46df400b5bb9996f9d74476997e
> 
> commit 4395d3ced5cfa46df400b5bb9996f9d74476997e
> Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
> AuthorDate: 2024-04-24 11:31:54 +0000
> Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
> CommitDate: 2024-04-25 09:42:59 +0000
> 
>     Document that gettimeofday() is obsolescent
>     
>     Reported by:    kaktus
>     Reviewed by:    kaktus, pstef
>     MFC after:      3 days
>     Differential Revision:  https://reviews.freebsd.org/D23942
> ---
>  lib/libsys/gettimeofday.2 | 25 ++++++++++++++++++++++++-
>  1 file changed, 24 insertions(+), 1 deletion(-)
> 
> diff --git a/lib/libsys/gettimeofday.2 b/lib/libsys/gettimeofday.2
> index 5b867aaad33c..cfba97149199 100644
> --- a/lib/libsys/gettimeofday.2
> +++ b/lib/libsys/gettimeofday.2
> @@ -25,7 +25,7 @@
>  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
>  .\" SUCH DAMAGE.
>  .\"
> -.Dd May 13, 2021
> +.Dd April 24, 2024
>  .Dt GETTIMEOFDAY 2
>  .Os
>  .Sh NAME
> @@ -41,6 +41,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
> @@ -121,6 +132,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.
Obviously gettimeofday(2) is not going to be removed even in the far future.

>  .Sh HISTORY
>  The
>  .Fn gettimeofday