time.h.0p (9262B)
- '\" et
- .TH time.h "0P" 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
- time.h
- \(em time types
- .SH SYNOPSIS
- .LP
- .nf
- #include <time.h>
- .fi
- .SH DESCRIPTION
- Some of the functionality described on this reference page extends the
- ISO\ C standard. Applications shall define the appropriate feature test macro
- (see the System Interfaces volume of POSIX.1\(hy2017,
- .IR "Section 2.2" ", " "The Compilation Environment")
- to enable the visibility of these symbols in this header.
- .P
- The
- .IR <time.h>
- header shall define the
- .BR clock_t ,
- .BR size_t ,
- .BR time_t ,
- types as described in
- .IR <sys/types.h> .
- .P
- The
- .IR <time.h>
- header shall define the
- .BR clockid_t
- and
- .BR timer_t
- types as described in
- .IR <sys/types.h> .
- .P
- The
- .IR <time.h>
- header shall define the
- .BR locale_t
- type as described in
- .IR <locale.h> .
- .P
- The
- .IR <time.h>
- header shall define the
- .BR pid_t
- type as described in
- .IR <sys/types.h> .
- .P
- The tag
- .BR sigevent
- shall be declared as naming an incomplete structure type, the contents
- of which are described in the
- .IR <signal.h>
- header.
- .P
- The
- .IR <time.h>
- header shall declare the
- .BR tm
- structure, which shall include at least the following members:
- .sp
- .RS 4
- .nf
- int tm_sec \fRSeconds [0,60].\fR
- int tm_min \fRMinutes [0,59].\fR
- int tm_hour \fRHour [0,23].\fR
- int tm_mday \fRDay of month [1,31].\fR
- int tm_mon \fRMonth of year [0,11].\fR
- int tm_year \fRYears since 1900.\fR
- int tm_wday \fRDay of week [0,6] (Sunday =0).\fR
- int tm_yday \fRDay of year [0,365].\fR
- int tm_isdst \fRDaylight Savings flag.\fR
- .fi
- .P
- .RE
- .P
- The value of
- .IR tm_isdst
- shall be positive if Daylight Savings Time is in effect, 0 if Daylight
- Savings Time is not in effect, and negative if the information is not
- available.
- .P
- The
- .IR <time.h>
- header shall declare the
- .BR timespec
- structure, which shall include at least the following members:
- .sp
- .RS 4
- .nf
- time_t tv_sec \fRSeconds.\fR
- long tv_nsec \fRNanoseconds.\fR
- .fi
- .P
- .RE
- .P
- The
- .IR <time.h>
- header shall also declare the
- .BR itimerspec
- structure, which shall include at least the following members:
- .sp
- .RS 4
- .nf
- struct timespec it_interval \fRTimer period.\fR
- struct timespec it_value \fRTimer expiration.\fR
- .fi
- .P
- .RE
- .P
- The
- .IR <time.h>
- header shall define the following macros:
- .IP NULL 14
- As described in
- .IR <stddef.h> .
- .IP CLOCKS_PER_SEC 14
- A number used to convert the value returned by the
- \fIclock\fR()
- function into seconds. The value shall be an expression with type
- .BR clock_t .
- The value of CLOCKS_PER_SEC shall be 1 million
- on XSI-conformant systems. However, it may be variable on other systems,
- and it should not be assumed that CLOCKS_PER_SEC is a compile-time
- constant.
- .P
- The
- .IR <time.h>
- header shall define the following symbolic constants. The values shall
- have a type that is assignment-compatible with
- .BR clockid_t .
- .IP CLOCK_MONOTONIC 14
- .br
- The identifier for the system-wide monotonic clock, which is defined as
- a clock measuring real time, whose value cannot be set via
- \fIclock_settime\fR()
- and which cannot have negative clock jumps. The maximum possible clock
- jump shall be implementation-defined.
- .IP CLOCK_PROCESS_CPUTIME_ID 14
- .br
- The identifier of the CPU-time clock associated with the process
- making a
- \fIclock\fR()
- or
- .IR timer* (\|)
- function call.
- .IP CLOCK_REALTIME 14
- The identifier of the system-wide clock measuring real time.
- .IP CLOCK_THREAD_CPUTIME_ID 14
- .br
- The identifier of the CPU-time clock associated with the thread making a
- \fIclock\fR()
- or
- .IR timer* (\|)
- function call.
- .P
- The
- .IR <time.h>
- header shall define the following symbolic constant:
- .IP TIMER_ABSTIME 14
- Flag indicating time is absolute. For functions taking timer objects,
- this refers to the clock associated with the timer.
- .P
- The
- .IR <time.h>
- header shall provide a declaration or definition for
- .IR getdate_err .
- The
- .IR getdate_err
- symbol shall expand to an expression of type
- .BR int .
- It is unspecified whether
- .IR getdate_err
- is a macro or an identifier declared with external linkage, and whether or
- not it is a modifiable lvalue. If a macro definition is suppressed in
- order to access an actual object, or a program defines an identifier
- with the name
- .IR getdate_err ,
- the behavior is undefined.
- .P
- The following shall be declared as functions and may also be defined
- as macros. Function prototypes shall be provided.
- .sp
- .RS 4
- .nf
- char *asctime(const struct tm *);
- char *asctime_r(const struct tm *restrict, char *restrict);
- clock_t clock(void);
- int clock_getcpuclockid(pid_t, clockid_t *);
- int clock_getres(clockid_t, struct timespec *);
- int clock_gettime(clockid_t, struct timespec *);
- int clock_nanosleep(clockid_t, int, const struct timespec *,
- struct timespec *);
- int clock_settime(clockid_t, const struct timespec *);
- char *ctime(const time_t *);
- char *ctime_r(const time_t *, char *);
- double difftime(time_t, time_t);
- struct tm *getdate(const char *);
- struct tm *gmtime(const time_t *);
- struct tm *gmtime_r(const time_t *restrict, struct tm *restrict);
- struct tm *localtime(const time_t *);
- struct tm *localtime_r(const time_t *restrict, struct tm *restrict);
- time_t mktime(struct tm *);
- int nanosleep(const struct timespec *, struct timespec *);
- size_t strftime(char *restrict, size_t, const char *restrict,
- const struct tm *restrict);
- size_t strftime_l(char *restrict, size_t, const char *restrict,
- const struct tm *restrict, locale_t);
- char *strptime(const char *restrict, const char *restrict,
- struct tm *restrict);
- time_t time(time_t *);
- int timer_create(clockid_t, struct sigevent *restrict,
- timer_t *restrict);
- int timer_delete(timer_t);
- int timer_getoverrun(timer_t);
- int timer_gettime(timer_t, struct itimerspec *);
- int timer_settime(timer_t, int, const struct itimerspec *restrict,
- struct itimerspec *restrict);
- void tzset(void);
- .fi
- .P
- .RE
- .br
- .P
- The
- .IR <time.h>
- header shall declare the following as variables:
- .sp
- .RS 4
- .nf
- extern int daylight;
- extern long timezone;
- extern char *tzname[];
- .fi
- .P
- .RE
- .P
- Inclusion of the
- .IR <time.h>
- header may make visible all symbols from the
- .IR <signal.h>
- header.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The range [0,60] for
- .IR tm_sec
- allows for the occasional leap second.
- .P
- .IR tm_year
- is a signed value; therefore, years before 1900 may be represented.
- .P
- To obtain the number of clock ticks per second returned by the
- \fItimes\fR()
- function, applications should call
- .IR sysconf (_SC_CLK_TCK).
- .SH RATIONALE
- The range [0,60] seconds allows for positive or negative leap seconds.
- The formal definition of UTC does not permit double leap seconds, so
- all mention of double leap seconds has been removed, and the range
- shortened from the former [0,61] seconds seen in earlier versions of
- this standard.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fB<locale.h>\fP",
- .IR "\fB<signal.h>\fP",
- .IR "\fB<stddef.h>\fP",
- .IR "\fB<sys_types.h>\fP"
- .P
- .ad l
- The System Interfaces volume of POSIX.1\(hy2017,
- .IR "Section 2.2" ", " "The Compilation Environment",
- .IR "\fIasctime\fR\^(\|)",
- .IR "\fIclock\fR\^(\|)",
- .IR "\fIclock_getcpuclockid\fR\^(\|)",
- .IR "\fIclock_getres\fR\^(\|)",
- .IR "\fIclock_nanosleep\fR\^(\|)",
- .IR "\fIctime\fR\^(\|)",
- .IR "\fIdifftime\fR\^(\|)",
- .IR "\fIgetdate\fR\^(\|)",
- .IR "\fIgmtime\fR\^(\|)",
- .IR "\fIlocaltime\fR\^(\|)",
- .IR "\fImktime\fR\^(\|)",
- .IR "\fImq_receive\fR\^(\|)",
- .IR "\fImq_send\fR\^(\|)",
- .IR "\fInanosleep\fR\^(\|)",
- .IR "\fIpthread_getcpuclockid\fR\^(\|)",
- .IR "\fIpthread_mutex_timedlock\fR\^(\|)",
- .IR "\fIpthread_rwlock_timedrdlock\fR\^(\|)",
- .IR "\fIpthread_rwlock_timedwrlock\fR\^(\|)",
- .IR "\fIsem_timedwait\fR\^(\|)",
- .IR "\fIstrftime\fR\^(\|)",
- .IR "\fIstrptime\fR\^(\|)",
- .IR "\fIsysconf\fR\^(\|)",
- .IR "\fItime\fR\^(\|)",
- .IR "\fItimer_create\fR\^(\|)",
- .IR "\fItimer_delete\fR\^(\|)",
- .IR "\fItimer_getoverrun\fR\^(\|)",
- .IR "\fItzset\fR\^(\|)",
- .IR "\fIutime\fR\^(\|)"
- .ad b
- .\"
- .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 .