diff options
Diffstat (limited to 'upstream/archlinux/man3p/clock_getres.3p')
| -rw-r--r-- | upstream/archlinux/man3p/clock_getres.3p | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/clock_getres.3p b/upstream/archlinux/man3p/clock_getres.3p new file mode 100644 index 00000000..76be2f97 --- /dev/null +++ b/upstream/archlinux/man3p/clock_getres.3p @@ -0,0 +1,286 @@ +'\" et +.TH CLOCK_GETRES "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +clock_getres, +clock_gettime, +clock_settime +\(em clock and timer functions +.SH SYNOPSIS +.LP +.nf +#include <time.h> +.P +int clock_getres(clockid_t \fIclock_id\fP, struct timespec *\fIres\fP); +int clock_gettime(clockid_t \fIclock_id\fP, struct timespec *\fItp\fP); +int clock_settime(clockid_t \fIclock_id\fP, const struct timespec *\fItp\fP); +.fi +.SH DESCRIPTION +The +\fIclock_getres\fR() +function shall return the resolution of any clock. Clock resolutions +are implementation-defined and cannot be set by a process. If the +argument +.IR res +is not NULL, the resolution of the specified clock shall be stored in the +location pointed to by +.IR res . +If +.IR res +is NULL, the clock resolution is not returned. If the +.IR time +argument of +\fIclock_settime\fR() +is not a multiple of +.IR res , +then the value is truncated to a multiple of +.IR res . +.P +The +\fIclock_gettime\fR() +function shall return the current value +.IR tp +for the specified clock, +.IR clock_id . +.P +The +\fIclock_settime\fR() +function shall set the specified clock, +.IR clock_id , +to the value specified by +.IR tp . +Time values that are between two consecutive non-negative integer +multiples of the resolution of the specified clock shall be truncated +down to the smaller multiple of the resolution. +.P +A clock may be system-wide (that is, visible to all processes) or +per-process (measuring time that is meaningful only within a process). +All implementations shall support a +.IR clock_id +of CLOCK_REALTIME as defined in +.IR <time.h> . +This clock represents the clock measuring real time for the system. +For this clock, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of time (in seconds and nanoseconds) since the +Epoch. An implementation may also support additional clocks. The +interpretation of time values for these clocks is unspecified. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time of +expiration for absolute time services based upon the CLOCK_REALTIME +clock. This applies to the time at which armed absolute timers expire. +If the absolute time requested at the invocation of such a time service +is before the new value of the clock, the time service shall expire +immediately as if the clock had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on threads that are blocked waiting for a relative +time service based upon this clock, including the +\fInanosleep\fR() +function; nor on the expiration of relative timers based upon this +clock. Consequently, these time services shall expire when the +requested relative interval elapses, independently of the new or old +value of the clock. +.P +If the Monotonic Clock option is supported, all implementations shall +support a +.IR clock_id +of CLOCK_MONOTONIC defined in +.IR <time.h> . +This clock represents the monotonic clock for the system. For this +clock, the value returned by +\fIclock_gettime\fR() +represents the amount of time (in seconds and nanoseconds) since an +unspecified point in the past (for example, system start-up time, or the +Epoch). This point does not change after system start-up time. The value +of the CLOCK_MONOTONIC clock cannot be set via +\fIclock_settime\fR(). +This function shall fail if it is invoked with a +.IR clock_id +argument of CLOCK_MONOTONIC. +.P +The effect of setting a clock via +\fIclock_settime\fR() +on armed per-process timers associated with a clock other than +CLOCK_REALTIME is implementation-defined. +.P +If the value of the CLOCK_REALTIME clock is set via +\fIclock_settime\fR(), +the new value of the clock shall be used to determine the time at which +the system shall awaken a thread blocked on an absolute +\fIclock_nanosleep\fR() +call based upon the CLOCK_REALTIME clock. If the absolute time +requested at the invocation of such a time service is before the new +value of the clock, the call shall return immediately as if the clock +had reached the requested time normally. +.P +Setting the value of the CLOCK_REALTIME clock via +\fIclock_settime\fR() +shall have no effect on any thread that is blocked on a relative +\fIclock_nanosleep\fR() +call. Consequently, the call shall return when the requested relative +interval elapses, independently of the new or old value of the clock. +.P +Appropriate privileges to set a particular clock are +implementation-defined. +.P +If _POSIX_CPUTIME is defined, implementations shall support clock ID +values obtained by invoking +\fIclock_getcpuclockid\fR(), +which represent the CPU-time clock of a given process. Implementations +shall also support the special +.BR clockid_t +value CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of +the calling process when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +represent the amount of execution time of the process associated with +the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.P +If _POSIX_THREAD_CPUTIME is defined, implementations shall support +clock ID values obtained by invoking +\fIpthread_getcpuclockid\fR(), +which represent the CPU-time clock of a given thread. Implementations +shall also support the special +.BR clockid_t +value CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of +the calling thread when invoking one of the +.IR clock_* (\|) +or +.IR timer_* (\|) +functions. For these clock IDs, the values returned by +\fIclock_gettime\fR() +and specified by +\fIclock_settime\fR() +shall represent the amount of execution time of the thread associated +with the clock. Changing the value of a CPU-time clock via +\fIclock_settime\fR() +shall have no effect on the behavior of the sporadic server scheduling +policy (see +.IR "Scheduling Policies"). +.SH "RETURN VALUE" +A return value of 0 shall indicate that the call succeeded. A return +value of \-1 shall indicate that an error occurred, and +.IR errno +shall be set to indicate the error. +.SH ERRORS +The +\fIclock_getres\fR(), +\fIclock_gettime\fR(), +and +\fIclock_settime\fR() +functions shall fail if: +.TP +.BR EINVAL +The +.IR clock_id +argument does not specify a known clock. +.P +The +\fIclock_gettime\fR() +function shall fail if: +.TP +.BR EOVERFLOW +The number of seconds will not fit in an object of type +.BR time_t . +.P +The +\fIclock_settime\fR() +function shall fail if: +.TP +.BR EINVAL +The +.IR tp +argument to +\fIclock_settime\fR() +is outside the range for the given clock ID. +.TP +.BR EINVAL +The +.IR tp +argument specified a nanosecond value less than zero or greater than or +equal to 1\|000 million. +.TP +.BR EINVAL +The value of the +.IR clock_id +argument is CLOCK_MONOTONIC. +.P +The +\fIclock_settime\fR() +function may fail if: +.TP +.BR EPERM +The requesting process does not have appropriate privileges +to set the specified clock. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +Note that the absolute value of the monotonic clock is meaningless +(because its origin is arbitrary), and thus there is no need to set it. +Furthermore, realtime applications can rely on the fact that the value +of this clock is never set and, therefore, that time intervals measured +with this clock will not be affected by calls to +\fIclock_settime\fR(). +.SH RATIONALE +None. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.ad l +.IR "Scheduling Policies", +.IR "\fIclock_getcpuclockid\fR\^(\|)", +.IR "\fIclock_nanosleep\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fImq_receive\fR\^(\|)", +.IR "\fImq_send\fR\^(\|)", +.IR "\fInanosleep\fR\^(\|)", +.IR "\fIpthread_mutex_timedlock\fR\^(\|)", +.IR "\fIsem_timedwait\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fItimer_create\fR\^(\|)", +.IR "\fItimer_getoverrun\fR\^(\|)" +.ad b +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "\fB<time.h>\fP" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +In the event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |