Merging upstream version 6.8.

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

1 files changed, 152 insertions, 0 deletions

diff --git a/man/man3/adjtime.3 b/man/man3/adjtime.3
new file mode 100644
index 0000000..80f1485
--- /dev/null
+++ b/man/man3/adjtime.3
@@ -0,0 +1,152 @@
+'\" t
+.\" Copyright (c) 2006 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH adjtime 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+adjtime \- correct the time to synchronize the system clock
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/time.h>
+.P
+.BI "int adjtime(const struct timeval *" delta ", struct timeval *" olddelta );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR adjtime ():
+.nf
+    Since glibc 2.19:
+        _DEFAULT_SOURCE
+    glibc 2.19 and earlier:
+        _BSD_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR adjtime ()
+function gradually adjusts the system clock (as returned by
+.BR gettimeofday (2)).
+The amount of time by which the clock is to be adjusted is specified
+in the structure pointed to by
+.IR delta .
+This structure has the following form:
+.P
+.in +4n
+.EX
+struct timeval {
+    time_t      tv_sec;     /* seconds */
+    suseconds_t tv_usec;    /* microseconds */
+};
+.EE
+.in
+.P
+If the adjustment in
+.I delta
+is positive, then the system clock is speeded up by some
+small percentage (i.e., by adding a small
+amount of time to the clock value in each second) until the adjustment
+has been completed.
+If the adjustment in
+.I delta
+is negative, then the clock is slowed down in a similar fashion.
+.P
+If a clock adjustment from an earlier
+.BR adjtime ()
+call is already in progress
+at the time of a later
+.BR adjtime ()
+call, and
+.I delta
+is not NULL for the later call, then the earlier adjustment is stopped,
+but any already completed part of that adjustment is not undone.
+.P
+If
+.I olddelta
+is not NULL, then the buffer that it points to is used to return
+the amount of time remaining from any previous adjustment that
+has not yet been completed.
+.SH RETURN VALUE
+On success,
+.BR adjtime ()
+returns 0.
+On failure, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EINVAL
+The adjustment in
+.I delta
+is outside the permitted range.
+.TP
+.B EPERM
+The caller does not have sufficient privilege to adjust the time.
+Under Linux, the
+.B CAP_SYS_TIME
+capability is required.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR adjtime ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+None.
+.SH HISTORY
+4.3BSD, System V.
+.SH NOTES
+The adjustment that
+.BR adjtime ()
+makes to the clock is carried out in such a manner that the clock
+is always monotonically increasing.
+Using
+.BR adjtime ()
+to adjust the time prevents the problems that could be caused for certain
+applications (e.g.,
+.BR make (1))
+by abrupt positive or negative jumps in the system time.
+.P
+.BR adjtime ()
+is intended to be used to make small adjustments to the system time.
+Most systems impose a limit on the adjustment that can be specified in
+.IR delta .
+In the glibc implementation,
+.I delta
+must be less than or equal to (INT_MAX / 1000000 \- 2)
+and greater than or equal to (INT_MIN / 1000000 + 2)
+(respectively 2145 and \-2145 seconds on i386).
+.SH BUGS
+A longstanding bug
+.\" http://sourceware.org/bugzilla/show_bug?id=2449
+.\" http://bugzilla.kernel.org/show_bug.cgi?id=6761
+meant that if
+.I delta
+was specified as NULL,
+no valid information about the outstanding clock adjustment was returned in
+.IR olddelta .
+(In this circumstance,
+.BR adjtime ()
+should return the outstanding clock adjustment, without changing it.)
+This bug is fixed
+.\" Thanks to the new adjtimex() ADJ_OFFSET_SS_READ flag
+on systems with glibc 2.8 or later and
+Linux kernel 2.6.26 or later.
+.SH SEE ALSO
+.BR adjtimex (2),
+.BR gettimeofday (2),
+.BR time (7)