sl@0: /** @file ../include/time.h
sl@0: @internalComponent
sl@0: */
sl@0:
sl@0: /** @fn asctime(const struct tm *tm)
sl@0: @param tm
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock(void)
sl@0: @return clock is just for build support and hence returns 0.
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: The clock function
sl@0: determines the amount of processor time used since the invocation of the
sl@0: calling process, measured in CLOCKS_PER_SEC s of a second.
sl@0:
sl@0: Note: the clock system call eventually calls Symbian OS call user::GetCpuTime(),
sl@0: which is not supported from version 8.0b, hence this api is included for build
sl@0: support only.
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn ctime(const time_t *clock)
sl@0: @param clock
sl@0:
sl@0: Note: This description also covers the following functions -
sl@0: difftime() asctime() localtime() gmtime() mktime() ctime_r() localtime_r() gmtime_r() asctime_r()
sl@0:
sl@0: @return Each of these functions returns the value described, NULL, or -1 in the case of mktime if an error was detected.
sl@0:
sl@0: The functions ctime, gmtime and localtime all take as an argument a time value representing the time
sl@0: in seconds since the Epoch (00:00:00 UTC, January 1, 1970); see time
sl@0:
sl@0: The function localtime converts the time value pointed at by clock and returns a pointer to a " struct tm " (described below) which contains the broken down time information
sl@0: for the value after adjusting for the current time zone (and any other factors
sl@0: such as Daylight Saving Time). Time zone adjustments are performed as specified
sl@0: by the TZ environment variable (see the tzset function). localtime uses tzset to initialize time conversion information
sl@0: if tzset has not already been called by the process.
sl@0:
sl@0: After filling in the tm structure, localtime sets the tm_isdst's Nth element of tzname to a pointer to a ASCII string that is the time zone abbreviation to be
sl@0: used with localtime's (return, value.);
sl@0:
sl@0: The function gmtime similarly converts the time value without any time zone adjustment
sl@0: and returns a pointer to a tm structure (described below).
sl@0:
sl@0: The ctime function adjusts the time value for the current time zone, in
sl@0: the same manner as localtime, and returns a pointer to a 26-character string of the form: Thu Nov 24 18:22:48 1986
sl@0: \\0
sl@0:
sl@0: All the fields have constant width.
sl@0:
sl@0: The ctime_r function provides the same functionality as ctime except the caller must provide the output buffer buf to store the result, which must be at least 26 characters long.
sl@0:
sl@0: The localtime_r and gmtime_r functions provide the same functionality as localtime and gmtime respectively, except the caller must provide the output buffer result.
sl@0:
sl@0: The asctime function
sl@0: converts the broken down time in the structure tm pointed at by *tm to the form
sl@0: shown in the example above.
sl@0:
sl@0: The asctime_r function provides the same functionality as asctime except the caller provides the output buffer buf to store the result, which must be at least 26 characters long.
sl@0:
sl@0: The functions mktime converts the broken-down time in the structure pointed to by
sl@0: tm into a time value with the same encoding as that of the values returned by
sl@0: the time function (that is, seconds from the Epoch, UTC). The mktime function interprets the input structure according to the current
sl@0: timezone setting (see tzset ).
sl@0:
sl@0: The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values
sl@0: of the other components are not restricted to their normal ranges and will be
sl@0: normalized if needed. For example, October 40 is changed into November 9, a tm_hour of -1 means 1 hour before midnight, tm_mday of 0 means the day preceding the current month, and tm_mon of -2 means 2 months before January of tm_year.
sl@0:
sl@0: A positive or zero value for tm_isdst causes mktime to presume initially that summer time (for example, Daylight
sl@0: Saving Time) is or is not in effect for the specified time.. A negative value
sl@0: for tm_isdst causes the mktime function to attempt to define whether summer time is in effect
sl@0: for the specified time. The tm_isdst and tm_gmtoff members are forced to zero by timegm.
sl@0:
sl@0: On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately and the other
sl@0: components are set to represent the specified calendar time, but with their
sl@0: values forced to their normal ranges: The final value of tm_mday is not set until tm_mon and tm_year are determined.
sl@0:
sl@0: The mktime function returns the specified calendar time. If the calendar
sl@0: time cannot be represented, it returns -1.
sl@0:
sl@0: The difftime function
sl@0: returns the difference between two calendar times, ( time1 - time0), expressed in seconds.
sl@0:
sl@0: External declarations as well as the tm structure definition are in the
sl@0: @code
sl@0: #include <time.h> include file. The tm structure includes
sl@0: @endcode
sl@0: at least the following fields:
sl@0:
sl@0: @code
sl@0:
sl@0: int tm_sec; // seconds (0 - 60)
sl@0: int tm_min; // minutes (0 - 59)
sl@0: int tm_hour; // hours (0 - 23)
sl@0: int tm_mday; // day of month (1 - 31)
sl@0: int tm_mon; // month of year (0 - 11)
sl@0: int tm_year; // year - 1900
sl@0: int tm_wday; // day of week (Sunday = 0)
sl@0: int tm_yday; // day of year (0 - 365)
sl@0: int tm_isdst; // is summer time in effect?
sl@0: char *tm_zone; // abbreviation of timezone name
sl@0: long tm_gmtoff; // offset from UTC in seconds
sl@0:
sl@0: @endcode
sl@0:
sl@0: The
sl@0: field tm_isdst is non-zero if summer time is in effect.
sl@0:
sl@0: The field tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive
sl@0: values indicating east of the Prime Meridian.
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: //Example usage of asctime,localtime and gmtime:
sl@0: #include <time.h>
sl@0: #include <stdio.h>
sl@0: int main(){
sl@0: time_t t;
sl@0: struct tm *timeptr;
sl@0: char* asc_time;
sl@0: t = time (NULL); //Get current time in seconds from Epoc
sl@0: //Fill tm struct w.r.t localtime using localtime
sl@0: timeptr = localtime (&t;);
sl@0: //Use this to convert it to a string indicating time w.r.t localtime
sl@0: asc_time = asctime (timeptr);
sl@0: printf ("Time from asctime w.r.t localtime : %s", asc_time);
sl@0: //Fill tm struct w.r.t GMT using gmtime
sl@0: timeptr = gmtime (&t;);
sl@0: //Use this to convert it to a string indicating time w.r.t GMT
sl@0: asc_time = asctime (timeptr);
sl@0: printf ("Time from asctime w.r.t gmtime : %s", asc_time);
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Time from asctime w.r.t localtime : Thu Jun 22 10:42:27 2006
sl@0: Time from asctime w.r.t gmtime : Thu Jun 22 05:12:27 2006
sl@0:
sl@0: @endcode
sl@0: @code
sl@0: //Example usage of ctime,mktime:
sl@0: #include <time.h>
sl@0: #include <stdio.h>
sl@0: int main(){
sl@0: time_t t;
sl@0: struct tm timeptr;
sl@0: char* c_time;
sl@0: //Fill the tm struct with values
sl@0: timeptr.tm_year = 2001;
sl@0: timeptr.tm_mon = 6;
sl@0: timeptr.tm_mday = 4;
sl@0: timeptr.tm_hour = 0;
sl@0: timeptr.tm_min = 0;
sl@0: timeptr.tm_sec = 1;
sl@0: timeptr.tm_isdst = -1;
sl@0: t = mktime (&timeptr;); //Call mktime to make time in seconds w.r.t epoc
sl@0: //Convert this to a string indicating time using ctime
sl@0: c_time = ctime (&t;);
sl@0: printf ("Time from ctime : %s", c_time);
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Time from ctime : Thu Jan 1 05:29:59 1970
sl@0:
sl@0: @endcode
sl@0: @code
sl@0: //Example usage of difftime:
sl@0: #include <time.h>
sl@0: #include <unistd.h>
sl@0: #include <stdio.h>
sl@0: int main(){
sl@0: time_t t0,t1,t2;
sl@0: //Set initial and final values
sl@0: t0 = 10;
sl@0: t1 = 20;
sl@0: t2 = difftime (t1, t0); //Find the time difference using difftime
sl@0: printf ("Result of difftime = %d", t2);
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Result of difftime = 10
sl@0:
sl@0: @endcode
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0: Bugs:
sl@0:
sl@0: Except for difftime, mktime, and the _r variants of the other functions,
sl@0: these functions leaves their result in an internal static object and return
sl@0: a pointer to that object.
sl@0: Subsequent calls to these
sl@0: function will modify the same object.
sl@0:
sl@0: The C Standard provides no mechanism for a program to modify its current
sl@0: local timezone setting, and the POSIX -standard method is not reentrant.
sl@0: (However, thread-safe implementations are provided
sl@0: in the POSIX threaded environment.)
sl@0:
sl@0: The tm_zone field of a returned tm
sl@0: structure points to a static array of characters,
sl@0: which will also be overwritten by any subsequent calls (as well as by
sl@0: subsequent call to tzset )
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn difftime(time_t time1, time_t time0)
sl@0: @param time1
sl@0: @param time0
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn gmtime(const time_t *clock)
sl@0: @param clock
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn localtime(const time_t *clock)
sl@0: @param clock
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0: The localtime() is not guaranteed to be thread safe.
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn mktime(struct tm *tm)
sl@0: @param tm
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn strftime(char * s, size_t maxsize, const char * format, const struct tm * t)
sl@0: @param s
sl@0: @param maxsize
sl@0: @param format
sl@0: @param t
sl@0:
sl@0: The strftime function formats the information from t into the buffer s according to the string pointed to by format .
sl@0: The format string consists of zero or more conversion specifications and
sl@0: ordinary characters.
sl@0: All ordinary characters are copied directly into the buffer.
sl@0: A conversion specification consists of a percent sign "\%"
sl@0: and one other character.
sl@0:
sl@0: No more than maxsize characters will be placed into the array. If the total number of resulting characters, including the terminating NULL character, is not more
sl@0: than maxsize , strftime returns the number of characters in the array, not counting
sl@0: the terminating NULL. Otherwise, zero is returned and the buffer contents are
sl@0: indeterminate.
sl@0:
sl@0: @code
sl@0: The conversion specifications are copied to the buffer after expansion as follows:-
sl@0: %A is replaced by national representation of the full weekday name.
sl@0: %a is replaced by national representation of the abbreviated weekday name.
sl@0: %B is replaced by national representation of the full month name.
sl@0: %b is replaced by national representation of the abbreviated month name.
sl@0: %C is replaced by (year / 100) as decimal number; single digits are preceded by a zero.
sl@0: %c is replaced by national representation of time and date.
sl@0: %D is equivalent to "%m/%d/%y".
sl@0: %d is replaced by the day of the month as a decimal number (01-31).
sl@0: %E* %O*
sl@0: POSIX locale extensions. The sequences %Ec %EC %Ex %EX %Ey %EY %Od %Oe %OH %OI %Om %OM %OS %Ou %OU %OV %Ow %OW %Oy are supposed to provide alternate representations.
sl@0: Additionally %OB implemented to represent alternative months names (used standalone, without day mentioned).
sl@0:
sl@0: %e is replaced by the day of month as a decimal number (1-31); single digits are preceded by a blank.
sl@0: %F is equivalent to "%Y-%m-%d".
sl@0: %G is replaced by a year as a decimal number with century. This year is the one that contains the greater part of the week (Monday as the first day of the week).
sl@0: %g is replaced by the same year as in "%G", but as a decimal number without century (00-99).
sl@0: %H is replaced by the hour (24-hour clock) as a decimal number (00-23).
sl@0: %h the same as %b.
sl@0: %I is replaced by the hour (12-hour clock) as a decimal number (01-12).
sl@0: %j is replaced by the day of the year as a decimal number (001-366).
sl@0: %k is replaced by the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank.
sl@0: %l is replaced by the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
sl@0: %M is replaced by the minute as a decimal number (00-59).
sl@0: %m is replaced by the month as a decimal number (01-12).
sl@0: %n is replaced by a newline.
sl@0: %O* the same as %E*.
sl@0: %p is replaced by national representation of either "ante meridiem" or "post meridiem" as appropriate.
sl@0: %R is equivalent to "%H:%M".
sl@0: %r is equivalent to "%I:%M:%S %p".
sl@0: %S is replaced by the second as a decimal number (00-60).
sl@0: %s is replaced by the number of seconds since the Epoch, UTC (see mktime).
sl@0: %T is equivalent to "%H:%M:%S".
sl@0: %t is replaced by a tab.
sl@0: %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number (00-53).
sl@0: %u is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7).
sl@0: %V is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.
sl@0: %v is equivalent to "%e-%b-%Y".
sl@0: %W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (00-53).
sl@0: %w is replaced by the weekday (Sunday as the first day of the week) as a decimal number (0-6).
sl@0: %X is replaced by national representation of the time.
sl@0: %x is replaced by national representation of the date.
sl@0: %Y is replaced by the year with century as a decimal number.
sl@0: %y is replaced by the year without century as a decimal number (00-99).
sl@0: %Z is replaced by the time zone name.
sl@0: %z is replaced by the time zone offset from UTC; a leading plus sign stands for east of UTC, a minus sign for west of UTC, hours and minutes follow with two digits each and no delimiter between them (common form for RFC 822 date headers).
sl@0: %+ is replaced by national representation of the date and time (the format is similar to that produced by 'date( )' function ).
sl@0: %-* GNU libc extension. Do not do any padding when performing numerical outputs.
sl@0: %_* GNU libc extension. Explicitly specify space for padding.
sl@0: %0* GNU libc extension. Explicitly specify zero for padding.
sl@0: %% is replaced by ‘%’.
sl@0: @endcode
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: #include <string.h>
sl@0: #include <stdio.h>
sl@0: #include <time.h>
sl@0: #include <locale.h>
sl@0: int main()
sl@0: {
sl@0: struct tm tm;
sl@0: char buf[255];
sl@0: char *locale;
sl@0: locale = setlocale(LC_TIME,"en_GB.ISO-8859-1");
sl@0: if( locale != NULL)
sl@0: {
sl@0: strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;);
sl@0: printf("sec = %d min = %d hours = %d
sl@0: Year = %d Month = %d day = %d
sl@0: ",\
sl@0: tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday);
sl@0: strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;);
sl@0: puts(buf);
sl@0: strptime("Mon","%a", &tm;);
sl@0: strftime(buf, sizeof(buf), "%a", &tm;);
sl@0: puts(buf);
sl@0: }
sl@0: else
sl@0: printf("Failed to set locale
sl@0: ");
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: sec = 1 min = 31 hours = 18
sl@0: Year = 101 Month = 10 day = 12
sl@0: 12 November 2001 18:31:01
sl@0: Mon
sl@0:
sl@0: @endcode
sl@0: @see printf()
sl@0: @see ctime()
sl@0: @see strptime()
sl@0: @see wcsftime()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn time(time_t *p)
sl@0: @param p
sl@0: @return On success the value of time in seconds since the Epoch is returned. On error
sl@0: (time_t)(-1) is returned and errno is set appropriately.
sl@0:
sl@0: The time function returns the value of time in seconds since 0 hours, 0
sl@0: minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If an error occurs, time returns the value ( time_t)(-1) .
sl@0:
sl@0: The return value is also stored in * p ,
sl@0: provided that p is non-null.
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: /*
sl@0: * Detailed description : sample usage of time system call
sl@0: */
sl@0: #include <time.h>
sl@0: int main()
sl@0: {
sl@0: time_t Time ;
sl@0: if(time(&Time;) < 0 )
sl@0: {
sl@0: printf("Time system call failed
sl@0: ") ;
sl@0: return -1 ;
sl@0: }
sl@0: printf("Time value is %u
sl@0: " , Time) ;
sl@0: return 0 ;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0:
sl@0: Time value is 1176916948
sl@0:
sl@0: @endcode
sl@0: @see gettimeofday()
sl@0: @see ctime()
sl@0:
sl@0:
sl@0: Bugs:
sl@0:
sl@0: Neither -isoC-99 nor -p1003.1-2001 requires time to set errno on failure; thus, it is impossible for an application to distinguish
sl@0: the valid time value -1 (representing the last UTC second of 1969)
sl@0: from the error return value.
sl@0:
sl@0: Systems conforming to earlier versions of the C and POSIX standards (including older versions of )
sl@0: did not set * p in the error case.
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn tzset(void)
sl@0:
sl@0: The tzset function
sl@0: initializes time conversion information used by the library routine localtime .
sl@0: The environment variable TZ specifies how this is done.
sl@0:
sl@0: If TZ does not appear in the environment, the best available approximation
sl@0: to local wall clock time is used.
sl@0:
sl@0: If TZ appears in the environment but its value is a null string, Coordinated
sl@0: Universal Time ( UTC )
sl@0: is used (without leap second correction).
sl@0:
sl@0:
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: #include <time.h>
sl@0: #include <stdio.h>
sl@0: int main(){
sl@0: time_t t;
sl@0: char* c_time;
sl@0: tzset(); //Call tzset
sl@0: c_time = ctime (&t;); //Get time-string using ctime for Epoc time
sl@0: printf ("Time from ctime after tzset: %s", c_time);
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Time from ctime after tzset: Sun Apr 7 02:24:08 1974
sl@0:
sl@0: @endcode
sl@0: @see gettimeofday()
sl@0: @see ctime()
sl@0: @see getenv()
sl@0: @see time()
sl@0:
sl@0:
sl@0: @see gettimeofday()
sl@0: @see ctime()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see gettimeofday()
sl@0: @see ctime()
sl@0: @see getenv()
sl@0: @see time()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock_getres(clockid_t clock_id, struct timespec *res)
sl@0: @param clock_id
sl@0: @param res
sl@0:
sl@0: Refer to clock_gettime() for the documentation
sl@0: @see adjtime()
sl@0: @see ctime()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock_gettime(clockid_t clock_id, struct timespec *tp)
sl@0: @param clock_id
sl@0: @param tp
sl@0:
sl@0: Note: This description also covers the following functions -
sl@0: clock_settime() clock_getres() clock_getcpuclockid()
sl@0:
sl@0: @return All the above APIs return 0 on success and -1 on failure.
sl@0:
sl@0: @code
sl@0: #include < sys/time.h > as:
sl@0: @endcode
sl@0: The clock_gettime and clock_settime allow the calling process to retrieve or set the value used by a clock
sl@0: which is specified by clock_id.
sl@0:
sl@0: The clock_id argument can be one of four values: CLOCK_REALTIME for time
sl@0: that increments as a wall clock should, CLOCK_MONOTONIC which increments in
sl@0: SI seconds, CLOCK_VIRTUAL for time that increments only when the CPU is running
sl@0: in user mode on behalf of the calling process, or CLOCK_PROF for time that increments
sl@0: when the CPU is running in user or kernel mode.
sl@0:
sl@0: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
sl@0: is supported for all the clock-based APIs.
sl@0:
sl@0: The structure pointed to by tp is defined in
sl@0: @code
sl@0: #include <sys/time.h> as:
sl@0: @endcode
sl@0:
sl@0: @code
sl@0: struct timespec {
sl@0: time_ttv_sec;/* seconds */
sl@0: longtv_nsec;/* and nanoseconds */
sl@0: };
sl@0: @endcode
sl@0:
sl@0: The resolution (granularity) of a clock is returned by the clock_getres system call.
sl@0: This value is placed in a (non-NULL) *tp.
sl@0:
sl@0: The clock_getcpuclockid system call returns ( in *clock_id ) the clock ID of the CPU-time clock of the process specified
sl@0: by pid. If pid is zero, the clock ID of the CPU-time clock of the process making
sl@0: the call is returned.
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: #include <time.h>
sl@0: #include <stdio.h>
sl@0: int clock_user()
sl@0: {
sl@0: struct timespec tp;
sl@0: int retval;
sl@0: clockid_t clockid;
sl@0: clock_getres (CLOCK_REALTIME, &tp;); // Call clock_getres
sl@0: printf ("Real time-clock resolution is %d seconds and %d nanoseconds
sl@0: ", tp.tv_sec, tp.tv_nsec);
sl@0: clock_getcpuclockid (0 ,&clockid;); // Call clock_getcpuclockid with pid = 0
sl@0: printf ("The clock id for the current process is %d
sl@0: ", clockid);
sl@0: tp.tv_sec = 0;
sl@0: tp.tv_nsec = 100;
sl@0: retval = clock_settime (CLOCK_REALTIME, &tp;); // Call clock_settime with 100ns
sl@0: printf ("clock_settime returned %d
sl@0: ", retval);
sl@0: clock_gettime (CLOCK_REALTIME, &tp;); // Call clock_gettime to fill tp
sl@0: printf ("Time from real time-clock is %d seconds and %d nanoseconds
sl@0: ", tp.tv_sec, tp.tv_nsec);
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Real time-clock resolution is 0 seconds and 1000000 nanoseconds
sl@0: The clock id for the current process is 0
sl@0: clock_settime returned 0
sl@0: Time from real time-clock is 0 seconds and 70663000 nanoseconds
sl@0:
sl@0: @endcode
sl@0: @see adjtime()
sl@0: @see ctime()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock_settime(clockid_t clock_id, const struct timespec *tp)
sl@0: @param clock_id
sl@0: @param tp
sl@0:
sl@0: Refer to clock_gettime() for the documentation
sl@0:
sl@0: @see adjtime()
sl@0: @see ctime()
sl@0:
sl@0: @capability Deferred @ref User::SetUTCTime(const TTime &aUTCTime)
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn nanosleep(const struct timespec *req, struct timespec *rem)
sl@0: @param req
sl@0: @param rem
sl@0: @return If the nanosleep system call returns because the requested time has elapsed, the value
sl@0: returned will be zero. If rem is non- NULL, the timespec structure it references is updated to contain the
sl@0: unslept amount (the request time minus the time actually slept).
sl@0:
sl@0: The nanosleep system call
sl@0: causes the process to sleep for the specified time.
sl@0: Currently only microsecond sleep resolution can be obtained.
sl@0:
sl@0:
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: /*
sl@0: * Detailed description: Sample usage of nanosleep system call.
sl@0: */
sl@0: #include <stdio.h>
sl@0: #include <time.h>
sl@0: int main()
sl@0: {
sl@0: struct timespec tim, tim2;
sl@0: tim.tv_sec = 1;
sl@0: tim.tv_nsec = 500;
sl@0: if(nanosleep(&tim; , &tim2;) < 0 ) {
sl@0: printf("Nano sleep system call failed
sl@0: ");
sl@0: return -1;
sl@0: }
sl@0: printf("Nano sleep successfull
sl@0: ");
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: Nano sleep successfull
sl@0:
sl@0: @endcode
sl@0: @see sleep()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock_getcpuclockid(pid_t pid, clockid_t* clock_id)
sl@0: @param pid
sl@0: @param clock_id
sl@0:
sl@0: Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
sl@0: is supported for all the clock-based APIs. Any value for pid except "0" is considered as invalid
sl@0: and for "0" the supported 'clock_id' i.e, CLOCK_REALTIME is returned.
sl@0:
sl@0: Refer to clock_gettime() for the documentation
sl@0: @see adjtime()
sl@0: @see ctime()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn clock_nanosleep (clockid_t clock_id, int flags,
sl@0: const struct timespec *rqtp, struct timespec *rmtp)
sl@0: @param clock_id
sl@0: @param flags
sl@0: @param rqtp
sl@0: @param rmtp
sl@0:
sl@0: For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/clock_nanosleep.html
sl@0:
sl@0: Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
sl@0: is supported for all the clock-based APIs.
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn asctime_r(const struct tm *tm, char *buf)
sl@0: @param tm
sl@0: @param buf
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn ctime_r(const time_t *clock, char *buf)
sl@0: @param clock
sl@0: @param buf
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn gmtime_r(const time_t *clock, struct tm *result)
sl@0: @param clock
sl@0: @param result
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0:
sl@0: /** @fn localtime_r(const time_t *clock, struct tm *result)
sl@0: @param clock
sl@0: @param result
sl@0:
sl@0: Refer to ctime() for the documentation
sl@0: @see gettimeofday()
sl@0: @see getenv()
sl@0: @see time()
sl@0: @see tzset()
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0:
sl@0: /** @fn strptime(const char * buf, const char * fmt, struct tm * tm)
sl@0: @param buf
sl@0: @param fmt
sl@0: @param tm
sl@0: @return Upon successful completion, strptime returns the pointer to the first character in buf that has not been required to satisfy the specified conversions in fmt .
sl@0: It returns NULL if one of the conversions failed.
sl@0:
sl@0: The strptime function parses the string in the buffer buf according to the string pointed to by fmt ,
sl@0: and fills in the elements of the structure pointed to by tm .
sl@0: The resulting values will be relative to the local time zone.
sl@0: Thus, it can be considered the reverse operation of strftime .
sl@0:
sl@0: The fmt string consists of zero or more conversion specifications and
sl@0: ordinary characters.
sl@0: All ordinary characters are matched exactly with the buffer, where
sl@0: white space in the fmt string will match any amount of white space
sl@0: in the buffer.
sl@0: All conversion specifications are identical to those described in strftime .
sl@0:
sl@0: Two-digit year values, including formats \%y and \%D ,
sl@0: are now interpreted as beginning at 1969 per POSIX requirements.
sl@0: Years 69-00 are interpreted in the 20th century (1969-2000), years
sl@0: 01-68 in the 21st century (2001-2068).
sl@0:
sl@0: If the fmt string does not contain enough conversion specifications to completely
sl@0: specify the resulting struct tm ,
sl@0: the unspecified members of tm are left untouched.
sl@0: For example, if format is "\%H:\%M:\%S",
sl@0: only tm_hour , tm_sec and tm_min will be modified.
sl@0: If time relative to today is desired, initialize the tm structure with today's date before passing it to strptime .
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: #include <string.h>
sl@0: #include <stdio.h>
sl@0: #include <time.h>
sl@0: #include <locale.h>
sl@0: int main()
sl@0: {
sl@0: struct tm tm;
sl@0: char buf[255];
sl@0: char *locale;
sl@0: locale = setlocale(LC_TIME,"en_GB.ISO-8859-1");
sl@0: if( locale != NULL)
sl@0: {
sl@0: strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;);
sl@0: printf("sec = %d min = %d hours = %d
sl@0: Year = %d Month = %d day = %d
sl@0: ",
sl@0: tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday);
sl@0: strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;);
sl@0: puts(buf);
sl@0: strptime("Mon","%a", &tm;);
sl@0: strftime(buf, sizeof(buf), "%a", &tm;);
sl@0: puts(buf);
sl@0: }
sl@0: else
sl@0: printf("Failed to set locale");
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: sec = 1 min = 31 hours = 18
sl@0: Year = 101 Month = 10 day = 12
sl@0: 12 November 2001 18:31:01
sl@0: Mon
sl@0:
sl@0: @endcode
sl@0: @see scanf()
sl@0: @see strftime()
sl@0:
sl@0:
sl@0: Bugs:
sl@0:
sl@0: Both the \%e and \%l format specifiers may incorrectly scan one too many digits
sl@0: if the intended values comprise only a single digit
sl@0: and that digit is followed immediately by another digit.
sl@0: Both specifiers accept zero-padded values,
sl@0: even though they are both defined as taking unpadded values.
sl@0:
sl@0: The \%p format specifier has no effect unless it is parsed after hour-related specifiers.
sl@0: Specifying \%l without \%p will produce undefined results.
sl@0: Note that 12AM
sl@0: (ante meridiem)
sl@0: is taken as midnight
sl@0: and 12PM
sl@0: (post meridiem)
sl@0: is taken as noon.
sl@0:
sl@0: The \%U and \%W format specifiers accept any value within the range 00 to 53
sl@0: without validating against other values supplied (like month
sl@0: or day of the year, for example).
sl@0:
sl@0: The \%Z format specifier only accepts time zone abbreviations of the local time zone,
sl@0: or the value "GMT".
sl@0: This limitation is because of ambiguity due to of the over loading of time
sl@0: zone abbreviations.
sl@0: One such example is EST which is both Eastern Standard Time and Eastern Australia Summer Time.
sl@0:
sl@0: The strptime function does not correctly handle multibyte characters in the fmt argument.
sl@0:
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn timer_create (clockid_t __clock_id,
sl@0: struct sigevent *__restrict __evp,
sl@0: timer_t *__restrict __timerid)
sl@0: @param __clock_id
sl@0: @param __evp
sl@0: @param __timerid
sl@0:
sl@0: For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_create.html
sl@0:
sl@0: Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
sl@0: is supported for all the clock-based APIs.
sl@0:
sl@0: @see timer_settime()
sl@0: @see timer_delete()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn timer_delete (timer_t __timerid)
sl@0: @param __timerid
sl@0:
sl@0: For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_delete.html
sl@0:
sl@0: @see timer_create()
sl@0: @see timer_settime()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn timer_settime(timer_t __timerid, int __flags,
sl@0: const struct itimerspec *__restrict __value,
sl@0: struct itimerspec *__restrict __ovalue)
sl@0: @param __timerid
sl@0: @param __flags
sl@0: @param __value
sl@0: @param __ovalue
sl@0:
sl@0: For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_settime.html
sl@0:
sl@0: Note: This description also covers the timer_gettime() and timer_getoverrun() functions.
sl@0:
sl@0: Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
sl@0: is supported for all the clock-based APIs. At the user level, Symbian OS supports upto a
sl@0: maximum of 1 ms resolution timer (RTimer::HighRes ()) upon which the timer emulation solution is based.
sl@0: As the re-registrations for a periodic timer happen in the user mode, the timer expirations
sl@0: might show up a possible unspecified latency.
sl@0:
sl@0: Examples:
sl@0: @code
sl@0: /*
sl@0: * Detailed description:
sl@0: */
sl@0: #include <time.h>
sl@0: #include <stdio.h>
sl@0: #include <signal.h>
sl@0: #include <pthread.h>
sl@0: #include <unistd.h>
sl@0:
sl@0: void sighler (union sigval val)
sl@0: {
sl@0: printf("In the handler with val:%d\n", val.sival_int);
sl@0: }
sl@0:
sl@0: int main()
sl@0: {
sl@0: timer_t timerid;
sl@0: struct sigevent sig;
sl@0:
sl@0: pthread_attr_t attr;
sl@0: pthread_attr_init( &attr );
sl@0:
sl@0: sig.sigev_notify = SIGEV_THREAD;
sl@0: sig.sigev_notify_function = sighler;
sl@0: sig.sigev_value.sival_int =20;
sl@0: sig.sigev_notify_attributes = &attr;
sl@0:
sl@0: if(0 == timer_create(CLOCK_REALTIME, &sig, &timerid))
sl@0: {
sl@0: struct itimerspec in, out;
sl@0:
sl@0: in.it_value.tv_sec = 1;
sl@0: in.it_value.tv_nsec = 0;
sl@0:
sl@0: in.it_interval.tv_sec = 0;
sl@0: in.it_interval.tv_nsec = 0;
sl@0:
sl@0: if(0 == timer_settime(timerid, 0, &in, &out))
sl@0: {
sl@0: sleep(3); //wait for the timer expirations...
sl@0: }
sl@0: else
sl@0: {
sl@0: printf("timer_settime () failed with err:%d\n", errno);
sl@0: }
sl@0:
sl@0: timer_delete(timerid);
sl@0: }
sl@0: else
sl@0: {
sl@0: printf("timer_create () failed with err:%d\n", errno);
sl@0: }
sl@0:
sl@0: return 0;
sl@0: }
sl@0:
sl@0: @endcode
sl@0: Output
sl@0: @code
sl@0: In the handler with val:20
sl@0:
sl@0: @endcode
sl@0: @see timer_create()
sl@0: @see timer_delete()
sl@0: @see clock_gettime()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn timer_gettime (timer_t __timerid, struct itimerspec *__value)
sl@0: @param __timerid
sl@0: @param __value
sl@0:
sl@0: For documentation refer to timer_settime().
sl@0:
sl@0: @see timer_create()
sl@0: @see timer_delete()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @fn timer_getoverrun (timer_t __timerid)
sl@0: @param __timerid
sl@0:
sl@0: For documentation refer to timer_settime().
sl@0:
sl@0: @see timer_create()
sl@0: @see timer_delete()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @def CLOCK_REALTIME
sl@0:
sl@0: This clock represents the realtime clock for the system.
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @def CLOCK_VIRTUAL
sl@0:
sl@0: This clock represents the amount of time (in seconds and nanoseconds) that the calling process has spent executing code in the user's context. It is a per-process clock. It cannot be set by the user.
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @def TIMER_ABSTIME
sl@0:
sl@0: absolute timer
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @struct tm
sl@0:
sl@0: Contains the following members,
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */
sl@0:
sl@0: /** @var tm::tm_sec
sl@0: seconds after the minute
sl@0: */
sl@0:
sl@0: /** @var tm::tm_min
sl@0: minutes after the hour
sl@0: */
sl@0:
sl@0: /** @var tm::tm_hour
sl@0: hours since midnight
sl@0: */
sl@0:
sl@0: /** @var tm::tm_mday
sl@0: day of the month
sl@0: */
sl@0:
sl@0: /** @var tm::tm_mon
sl@0: months since January
sl@0: */
sl@0:
sl@0: /** @var tm::tm_year
sl@0: years since 1900
sl@0: */
sl@0:
sl@0: /** @var tm::tm_wday
sl@0: days since Sunday
sl@0: */
sl@0:
sl@0: /** @var tm::tm_yday
sl@0: days since January 1
sl@0: */
sl@0:
sl@0: /** @var tm::tm_isdst
sl@0: Daylight Savings Time flag
sl@0: */
sl@0:
sl@0: /** @var tm::tm_gmtoff
sl@0: offset from UTC in seconds
sl@0: */
sl@0:
sl@0: /** @var tm::tm_zone
sl@0: timezone abbreviation
sl@0: */
sl@0:
sl@0:
sl@0: /** @fn time_t timegm(struct tm *tmp)
sl@0:
sl@0: @param tmp
sl@0:
sl@0: Description:
sl@0: This function is inverses for gmtime.
sl@0: Converts struct tm to time_t, assuming the data in tm is UTC rather than local timezone.
sl@0:
sl@0: @see gmtime()
sl@0: @see localtime()
sl@0: @see mktime()
sl@0: @see tzset()
sl@0:
sl@0: @publishedAll
sl@0: @externallyDefinedApi
sl@0: */