mirror of https://github.com/mkerrisk/man-pages
245 lines
6.9 KiB
Plaintext
245 lines
6.9 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<time.h>" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" <time.h>
|
|
.SH NAME
|
|
time.h \- time types
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <time.h>\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
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 IEEE\ Std\ 1003.1-2001, Section 2.2, The Compilation Environment)
|
|
to enable the visibility of these symbols in this
|
|
header.
|
|
.LP
|
|
The \fI<time.h>\fP header shall declare the structure \fBtm\fP, which
|
|
shall include at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBint tm_sec \fP Seconds [0,60]. \fB
|
|
int tm_min \fP Minutes [0,59]. \fB
|
|
int tm_hour \fP Hour [0,23]. \fB
|
|
int tm_mday \fP Day of month [1,31]. \fB
|
|
int tm_mon \fP Month of year [0,11]. \fB
|
|
int tm_year \fP Years since 1900. \fB
|
|
int tm_wday \fP Day of week [0,6] (Sunday =0). \fB
|
|
int tm_yday \fP Day of year [0,365]. \fB
|
|
int tm_isdst\fP Daylight Savings flag. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The value of \fItm_isdst\fP 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.
|
|
.LP
|
|
The \fI<time.h>\fP header shall define the following symbolic names:
|
|
.TP 7
|
|
NULL
|
|
Null pointer constant.
|
|
.TP 7
|
|
CLOCKS_PER_SEC
|
|
A number used to convert the value returned by the \fIclock\fP() function
|
|
into
|
|
seconds.
|
|
.TP 7
|
|
CLOCK_PROCESS_CPUTIME_ID
|
|
.sp
|
|
The identifier of the CPU-time clock associated with the process making
|
|
a \fIclock\fP() or
|
|
\fItimer*\fP() function call.
|
|
.TP 7
|
|
CLOCK_THREAD_CPUTIME_ID
|
|
.sp
|
|
The identifier of the CPU-time clock associated with the thread making
|
|
a \fIclock\fP() or \fItimer*\fP() function call.
|
|
.sp
|
|
.LP
|
|
The \fI<time.h>\fP header shall declare the structure \fBtimespec\fP,
|
|
which has at least the following members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBtime_t tv_sec \fP Seconds. \fB
|
|
long tv_nsec \fP Nanoseconds. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fI<time.h>\fP header shall also declare the \fBitimerspec\fP
|
|
structure, which has at least the following
|
|
members:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBstruct timespec it_interval \fP Timer period. \fB
|
|
struct timespec it_value \fP Timer expiration. \fB
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The following manifest constants shall be defined:
|
|
.TP 7
|
|
CLOCK_REALTIME
|
|
The identifier of the system-wide realtime clock.
|
|
.TP 7
|
|
TIMER_ABSTIME
|
|
Flag indicating time is absolute. For functions taking timer objects,
|
|
this refers to the clock associated with the timer.
|
|
.TP 7
|
|
CLOCK_MONOTONIC
|
|
.sp
|
|
The identifier for the system-wide monotonic clock, which is defined
|
|
as a clock whose value cannot be set via \fIclock_settime\fP() and
|
|
which cannot have backward clock jumps. The maximum possible clock
|
|
jump shall be implementation-defined.
|
|
.sp
|
|
.LP
|
|
The \fBclock_t\fP, \fBsize_t\fP, \fBtime_t\fP, \fBclockid_t\fP,
|
|
and \fBtimer_t\fP types shall be defined as described in \fI<sys/types.h>\fP
|
|
\&.
|
|
.LP
|
|
Although the value of CLOCKS_PER_SEC is required to be 1 million on
|
|
all XSI-conformant systems, it may be variable on other
|
|
systems, and it should not be assumed that CLOCKS_PER_SEC is a compile-time
|
|
constant.
|
|
.LP
|
|
The \fI<time.h>\fP header shall provide a declaration for \fIgetdate_err\fP.
|
|
.LP
|
|
The following shall be declared as functions and may also be defined
|
|
as macros. Function prototypes shall be provided.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBchar *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);
|
|
|
|
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_gettime(timer_t, struct itimerspec *);
|
|
int timer_getoverrun(timer_t);
|
|
int timer_settime(timer_t, int, const struct itimerspec *restrict,
|
|
struct itimerspec *restrict);
|
|
|
|
|
|
void tzset(void);
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.sp
|
|
.LP
|
|
The following shall be declared as variables:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB
|
|
extern int daylight;
|
|
extern long timezone;
|
|
|
|
|
|
extern char *tzname[];
|
|
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Inclusion of the \fI<time.h>\fP header may make visible all symbols
|
|
from the \fI<signal.h>\fP header.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
The range [0,60] for \fItm_sec\fP allows for the occasional leap second.
|
|
.LP
|
|
\fItm_year\fP is a signed value; therefore, years before 1900 may
|
|
be represented.
|
|
.LP
|
|
To obtain the number of clock ticks per second returned by the \fItimes\fP()
|
|
function,
|
|
applications should call \fIsysconf\fP(_SC_CLK_TCK).
|
|
.SH RATIONALE
|
|
.LP
|
|
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
|
|
previous versions of POSIX.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fI<signal.h>\fP , \fI<sys/types.h>\fP , the System
|
|
Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIasctime\fP(), \fIclock\fP(),
|
|
\fIclock_getcpuclockid\fP(), \fIclock_getres\fP(), \fIclock_nanosleep\fP(),
|
|
\fIctime\fP(), \fIdifftime\fP(), \fIgetdate\fP(), \fIgmtime\fP(),
|
|
\fIlocaltime\fP(), \fImktime\fP(), \fInanosleep\fP(), \fIstrftime\fP(),
|
|
\fIstrptime\fP(), \fIsysconf\fP(), \fItime\fP(), \fItimer_create\fP(),
|
|
\fItimer_delete\fP(), \fItimer_getoverrun\fP(), \fItzname\fP, \fItzset\fP(),
|
|
\fIutime\fP()
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|