Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 296 insertions, 0 deletions

diff --git a/man/man2/gettimeofday.2 b/man/man2/gettimeofday.2
new file mode 100644
index 0000000..d963e1b
--- /dev/null
+++ b/man/man2/gettimeofday.2
@@ -0,0 +1,296 @@
+.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified by Michael Haardt (michael@moria.de)
+.\" Modified 1993-07-23 by Rik Faith (faith@cs.unc.edu)
+.\" Modified 1994-08-21 by Michael Chastain (mec@shell.portal.com):
+.\"   Fixed necessary '#include' lines.
+.\" Modified 1995-04-15 by Michael Chastain (mec@shell.portal.com):
+.\"   Added reference to adjtimex.
+.\" Removed some nonsense lines pointed out by Urs Thuermann,
+.\"   (urs@isnogud.escape.de), aeb, 950722.
+.\" Modified 1997-01-14 by Austin Donnelly (and1000@debian.org):
+.\"   Added return values section, and bit on EFAULT
+.\" Added clarification on timezone, aeb, 971210.
+.\" Removed "#include <unistd.h>", aeb, 010316.
+.\" Modified, 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"   Added notes on capability requirement.
+.\"
+.TH gettimeofday 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+gettimeofday, settimeofday \- get / set time
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/time.h>
+.P
+.BI "int gettimeofday(struct timeval *restrict " tv ,
+.BI "                 struct timezone *_Nullable restrict " tz );
+.BI "int settimeofday(const struct timeval *" tv ,
+.BI "                 const struct timezone *_Nullable " tz );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR settimeofday ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    glibc 2.19 and earlier:
+        _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+The functions
+.BR gettimeofday ()
+and
+.BR settimeofday ()
+can get and set the time as well as a timezone.
+.P
+The
+.I tv
+argument is a
+.I struct timeval
+(as specified in
+.IR <sys/time.h> ):
+.P
+.in +4n
+.EX
+struct timeval {
+    time_t      tv_sec;     /* seconds */
+    suseconds_t tv_usec;    /* microseconds */
+};
+.EE
+.in
+.P
+and gives the number of seconds and microseconds since the Epoch (see
+.BR time (2)).
+.P
+The
+.I tz
+argument is a
+.IR "struct timezone" :
+.P
+.in +4n
+.EX
+struct timezone {
+    int tz_minuteswest;     /* minutes west of Greenwich */
+    int tz_dsttime;         /* type of DST correction */
+};
+.EE
+.in
+.P
+If either
+.I tv
+or
+.I tz
+is NULL, the corresponding structure is not set or returned.
+.\" FIXME . The compilation warning looks to be going away in glibc 2.17
+.\" see glibc commit 4b7634a5e03b0da6f8875de9d3f74c1cf6f2a6e8
+(However, compilation warnings will result if
+.I tv
+is NULL.)
+.\" The following is covered under EPERM below:
+.\" .P
+.\" Only the superuser may use
+.\" .BR settimeofday ().
+.P
+The use of the
+.I timezone
+structure is obsolete; the
+.I tz
+argument should normally be specified as NULL.
+(See NOTES below.)
+.P
+Under Linux, there are some peculiar "warp clock" semantics associated
+with the
+.BR settimeofday ()
+system call if on the very first call (after booting)
+that has a non-NULL
+.I tz
+argument, the
+.I tv
+argument is NULL and the
+.I tz_minuteswest
+field is nonzero.
+(The
+.I tz_dsttime
+field should be zero for this case.)
+In such a case it is assumed that the CMOS clock
+is on local time, and that it has to be incremented by this amount
+to get UTC system time.
+No doubt it is a bad idea to use this feature.
+.SH RETURN VALUE
+.BR gettimeofday ()
+and
+.BR settimeofday ()
+return 0 for success.
+On error, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EFAULT
+One of
+.I tv
+or
+.I tz
+pointed outside the accessible address space.
+.TP
+.B EINVAL
+.RB ( settimeofday ()):
+.I timezone
+is invalid.
+.TP
+.B EINVAL
+.RB ( settimeofday ()):
+.I tv.tv_sec
+is negative or
+.I tv.tv_usec
+is outside the range [0, 999,999].
+.TP
+.BR EINVAL " (since Linux 4.3)"
+.\" commit e1d7ba8735551ed79c7a0463a042353574b96da3
+.RB ( settimeofday ()):
+An attempt was made to set the time to a value less than
+the current value of the
+.B CLOCK_MONOTONIC
+clock (see
+.BR clock_gettime (2)).
+.TP
+.B EPERM
+The calling process has insufficient privilege to call
+.BR settimeofday ();
+under Linux the
+.B CAP_SYS_TIME
+capability is required.
+.SH VERSIONS
+.SS C library/kernel differences
+On some architectures, an implementation of
+.BR gettimeofday ()
+is provided in the
+.BR vdso (7).
+.P
+The kernel accepts NULL for both
+.I tv
+and
+.IR tz .
+The timezone argument is ignored by glibc and musl,
+and not passed to/from the kernel.
+Android's bionic passes the timezone argument to/from the kernel,
+but Android does not update the kernel timezone
+based on the device timezone in Settings,
+so the kernel's timezone is typically UTC.
+.SH STANDARDS
+.TP
+.BR gettimeofday ()
+POSIX.1-2008 (obsolete).
+.TP
+.BR settimeofday ()
+None.
+.SH HISTORY
+SVr4, 4.3BSD.
+POSIX.1-2001 describes
+.BR gettimeofday ()
+but not
+.BR settimeofday ().
+POSIX.1-2008 marks
+.BR gettimeofday ()
+as obsolete, recommending the use of
+.BR clock_gettime (2)
+instead.
+.P
+Traditionally, the fields of
+.I struct timeval
+were of type
+.IR long .
+.\"
+.SS The tz_dsttime field
+On a non-Linux kernel, with glibc, the
+.I tz_dsttime
+field of
+.I struct timezone
+will be set to a nonzero value by
+.BR gettimeofday ()
+if the current timezone has ever had or will have a daylight saving
+rule applied.
+In this sense it exactly mirrors the meaning of
+.BR daylight (3)
+for the current zone.
+On Linux, with glibc, the setting of the
+.I tz_dsttime
+field of
+.I struct timezone
+has never been used by
+.BR settimeofday ()
+or
+.BR gettimeofday ().
+.\" it has not
+.\" been and will not be supported by libc or glibc.
+.\" Each and every occurrence of this field in the kernel source
+.\" (other than the declaration) is a bug.
+Thus, the following is purely of historical interest.
+.P
+On old systems, the field
+.I tz_dsttime
+contains a symbolic constant (values are given below)
+that indicates in which part of the year Daylight Saving Time
+is in force.
+(Note: this value is constant throughout the year:
+it does not indicate that DST is in force, it just selects an
+algorithm.)
+The daylight saving time algorithms defined are as follows:
+.P
+.in +4n
+.EX
+\fBDST_NONE\fP     /* not on DST */
+\fBDST_USA\fP      /* USA style DST */
+\fBDST_AUST\fP     /* Australian style DST */
+\fBDST_WET\fP      /* Western European DST */
+\fBDST_MET\fP      /* Middle European DST */
+\fBDST_EET\fP      /* Eastern European DST */
+\fBDST_CAN\fP      /* Canada */
+\fBDST_GB\fP       /* Great Britain and Eire */
+\fBDST_RUM\fP      /* Romania */
+\fBDST_TUR\fP      /* Turkey */
+\fBDST_AUSTALT\fP  /* Australian style with shift in 1986 */
+.EE
+.in
+.P
+Of course it turned out that the period in which
+Daylight Saving Time is in force cannot be given
+by a simple algorithm, one per country; indeed,
+this period is determined by unpredictable political
+decisions.
+So this method of representing timezones
+has been abandoned.
+.SH NOTES
+The time returned by
+.BR gettimeofday ()
+.I is
+affected by discontinuous jumps in the system time
+(e.g., if the system administrator manually changes the system time).
+If you need a monotonically increasing clock, see
+.BR clock_gettime (2).
+.P
+Macros for operating on
+.I timeval
+structures are described in
+.BR timeradd (3).
+.SH SEE ALSO
+.BR date (1),
+.BR adjtimex (2),
+.BR clock_gettime (2),
+.BR time (2),
+.BR ctime (3),
+.BR ftime (3),
+.BR timeradd (3),
+.BR capabilities (7),
+.BR time (7),
+.BR vdso (7),
+.BR hwclock (8)