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: */