1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/time.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,1153 @@
1.4 +/** @file ../include/time.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +/** @fn asctime(const struct tm *tm)
1.9 +@param tm
1.10 +
1.11 +Refer to ctime() for the documentation
1.12 +@see gettimeofday()
1.13 +@see getenv()
1.14 +@see time()
1.15 +@see tzset()
1.16 +
1.17 +
1.18 +
1.19 +
1.20 +@publishedAll
1.21 +@externallyDefinedApi
1.22 +*/
1.23 +
1.24 +/** @fn clock(void)
1.25 +@return clock is just for build support and hence returns 0.
1.26 +
1.27 +
1.28 +
1.29 +
1.30 + The clock function
1.31 +determines the amount of processor time used since the invocation of the
1.32 +calling process, measured in CLOCKS_PER_SEC s of a second.
1.33 +
1.34 + Note: the clock system call eventually calls Symbian OS call user::GetCpuTime(),
1.35 + which is not supported from version 8.0b, hence this api is included for build
1.36 + support only.
1.37 +
1.38 +
1.39 +
1.40 +@publishedAll
1.41 +@externallyDefinedApi
1.42 +*/
1.43 +
1.44 +/** @fn ctime(const time_t *clock)
1.45 +@param clock
1.46 +
1.47 +Note: This description also covers the following functions -
1.48 + difftime() asctime() localtime() gmtime() mktime() ctime_r() localtime_r() gmtime_r() asctime_r()
1.49 +
1.50 +@return Each of these functions returns the value described, NULL, or -1 in the case of mktime if an error was detected.
1.51 +
1.52 + The functions ctime, gmtime and localtime all take as an argument a time value representing the time
1.53 +in seconds since the Epoch (00:00:00 UTC, January 1, 1970); see time
1.54 +
1.55 + 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
1.56 + for the value after adjusting for the current time zone (and any other factors
1.57 + such as Daylight Saving Time). Time zone adjustments are performed as specified
1.58 + by the TZ environment variable (see the tzset function). localtime uses tzset to initialize time conversion information
1.59 + if tzset has not already been called by the process.
1.60 +
1.61 + 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
1.62 +used with localtime's (return, value.);
1.63 +
1.64 + The function gmtime similarly converts the time value without any time zone adjustment
1.65 + and returns a pointer to a tm structure (described below).
1.66 +
1.67 + The ctime function adjusts the time value for the current time zone, in
1.68 + the same manner as localtime, and returns a pointer to a 26-character string of the form: Thu Nov 24 18:22:48 1986
1.69 +\\0
1.70 +
1.71 + All the fields have constant width.
1.72 +
1.73 + 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.
1.74 +
1.75 + 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.
1.76 +
1.77 + The asctime function
1.78 +converts the broken down time in the structure tm pointed at by *tm to the form
1.79 +shown in the example above.
1.80 +
1.81 + 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.
1.82 +
1.83 + The functions mktime converts the broken-down time in the structure pointed to by
1.84 + tm into a time value with the same encoding as that of the values returned by
1.85 + the time function (that is, seconds from the Epoch, UTC). The mktime function interprets the input structure according to the current
1.86 + timezone setting (see tzset ).
1.87 +
1.88 + The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values
1.89 + of the other components are not restricted to their normal ranges and will be
1.90 + 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.
1.91 +
1.92 + A positive or zero value for tm_isdst causes mktime to presume initially that summer time (for example, Daylight
1.93 + Saving Time) is or is not in effect for the specified time.. A negative value
1.94 + for tm_isdst causes the mktime function to attempt to define whether summer time is in effect
1.95 + for the specified time. The tm_isdst and tm_gmtoff members are forced to zero by timegm.
1.96 +
1.97 + On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately and the other
1.98 + components are set to represent the specified calendar time, but with their
1.99 + values forced to their normal ranges: The final value of tm_mday is not set until tm_mon and tm_year are determined.
1.100 +
1.101 + The mktime function returns the specified calendar time. If the calendar
1.102 + time cannot be represented, it returns -1.
1.103 +
1.104 + The difftime function
1.105 +returns the difference between two calendar times, ( time1 - time0), expressed in seconds.
1.106 +
1.107 + External declarations as well as the tm structure definition are in the
1.108 +@code
1.109 + #include <time.h> include file. The tm structure includes
1.110 +@endcode
1.111 + at least the following fields:
1.112 +
1.113 +@code
1.114 +
1.115 +int tm_sec; // seconds (0 - 60)
1.116 +int tm_min; // minutes (0 - 59)
1.117 +int tm_hour; // hours (0 - 23)
1.118 +int tm_mday; // day of month (1 - 31)
1.119 +int tm_mon; // month of year (0 - 11)
1.120 +int tm_year; // year - 1900
1.121 +int tm_wday; // day of week (Sunday = 0)
1.122 +int tm_yday; // day of year (0 - 365)
1.123 +int tm_isdst; // is summer time in effect?
1.124 +char *tm_zone; // abbreviation of timezone name
1.125 +long tm_gmtoff; // offset from UTC in seconds
1.126 +
1.127 +@endcode
1.128 +
1.129 + The
1.130 +field tm_isdst is non-zero if summer time is in effect.
1.131 +
1.132 + The field tm_gmtoff is the offset (in seconds) of the time represented from UTC, with positive
1.133 +values indicating east of the Prime Meridian.
1.134 +
1.135 +Examples:
1.136 +@code
1.137 +//Example usage of asctime,localtime and gmtime:
1.138 +#include <time.h>
1.139 +#include <stdio.h>
1.140 +int main(){
1.141 + time_t t;
1.142 + struct tm *timeptr;
1.143 + char* asc_time;
1.144 + t = time (NULL); //Get current time in seconds from Epoc
1.145 + //Fill tm struct w.r.t localtime using localtime
1.146 + timeptr = localtime (&t;);
1.147 + //Use this to convert it to a string indicating time w.r.t localtime
1.148 + asc_time = asctime (timeptr);
1.149 + printf ("Time from asctime w.r.t localtime : %s", asc_time);
1.150 + //Fill tm struct w.r.t GMT using gmtime
1.151 + timeptr = gmtime (&t;);
1.152 + //Use this to convert it to a string indicating time w.r.t GMT
1.153 + asc_time = asctime (timeptr);
1.154 + printf ("Time from asctime w.r.t gmtime : %s", asc_time);
1.155 + return 0;
1.156 +}
1.157 +
1.158 +@endcode
1.159 + Output
1.160 +@code
1.161 +Time from asctime w.r.t localtime : Thu Jun 22 10:42:27 2006
1.162 +Time from asctime w.r.t gmtime : Thu Jun 22 05:12:27 2006
1.163 +
1.164 +@endcode
1.165 +@code
1.166 +//Example usage of ctime,mktime:
1.167 +#include <time.h>
1.168 +#include <stdio.h>
1.169 +int main(){
1.170 + time_t t;
1.171 + struct tm timeptr;
1.172 + char* c_time;
1.173 + //Fill the tm struct with values
1.174 + timeptr.tm_year = 2001;
1.175 + timeptr.tm_mon = 6;
1.176 + timeptr.tm_mday = 4;
1.177 + timeptr.tm_hour = 0;
1.178 + timeptr.tm_min = 0;
1.179 + timeptr.tm_sec = 1;
1.180 + timeptr.tm_isdst = -1;
1.181 + t = mktime (&timeptr;); //Call mktime to make time in seconds w.r.t epoc
1.182 + //Convert this to a string indicating time using ctime
1.183 + c_time = ctime (&t;);
1.184 + printf ("Time from ctime : %s", c_time);
1.185 + return 0;
1.186 +}
1.187 +
1.188 +@endcode
1.189 + Output
1.190 +@code
1.191 +Time from ctime : Thu Jan 1 05:29:59 1970
1.192 +
1.193 +@endcode
1.194 +@code
1.195 +//Example usage of difftime:
1.196 +#include <time.h>
1.197 +#include <unistd.h>
1.198 +#include <stdio.h>
1.199 +int main(){
1.200 + time_t t0,t1,t2;
1.201 + //Set initial and final values
1.202 + t0 = 10;
1.203 + t1 = 20;
1.204 + t2 = difftime (t1, t0); //Find the time difference using difftime
1.205 + printf ("Result of difftime = %d", t2);
1.206 + return 0;
1.207 +}
1.208 +
1.209 +@endcode
1.210 + Output
1.211 +@code
1.212 +Result of difftime = 10
1.213 +
1.214 +@endcode
1.215 +@see gettimeofday()
1.216 +@see getenv()
1.217 +@see time()
1.218 +@see tzset()
1.219 +
1.220 +
1.221 +Bugs:
1.222 +
1.223 + Except for difftime, mktime, and the _r variants of the other functions,
1.224 +these functions leaves their result in an internal static object and return
1.225 +a pointer to that object.
1.226 +Subsequent calls to these
1.227 +function will modify the same object.
1.228 +
1.229 +The C Standard provides no mechanism for a program to modify its current
1.230 +local timezone setting, and the POSIX -standard method is not reentrant.
1.231 +(However, thread-safe implementations are provided
1.232 +in the POSIX threaded environment.)
1.233 +
1.234 +The tm_zone field of a returned tm
1.235 +structure points to a static array of characters,
1.236 +which will also be overwritten by any subsequent calls (as well as by
1.237 +subsequent call to tzset )
1.238 +
1.239 +
1.240 +@publishedAll
1.241 +@externallyDefinedApi
1.242 +*/
1.243 +
1.244 +/** @fn difftime(time_t time1, time_t time0)
1.245 +@param time1
1.246 +@param time0
1.247 +
1.248 +Refer to ctime() for the documentation
1.249 +@see gettimeofday()
1.250 +@see getenv()
1.251 +@see time()
1.252 +@see tzset()
1.253 +
1.254 +
1.255 +
1.256 +
1.257 +@publishedAll
1.258 +@externallyDefinedApi
1.259 +*/
1.260 +
1.261 +/** @fn gmtime(const time_t *clock)
1.262 +@param clock
1.263 +
1.264 +Refer to ctime() for the documentation
1.265 +@see gettimeofday()
1.266 +@see getenv()
1.267 +@see time()
1.268 +@see tzset()
1.269 +
1.270 +
1.271 +
1.272 +
1.273 +@publishedAll
1.274 +@externallyDefinedApi
1.275 +*/
1.276 +
1.277 +/** @fn localtime(const time_t *clock)
1.278 +@param clock
1.279 +
1.280 +Refer to ctime() for the documentation
1.281 +@see gettimeofday()
1.282 +@see getenv()
1.283 +@see time()
1.284 +@see tzset()
1.285 +
1.286 +
1.287 +The localtime() is not guaranteed to be thread safe.
1.288 +
1.289 +@publishedAll
1.290 +@externallyDefinedApi
1.291 +*/
1.292 +
1.293 +/** @fn mktime(struct tm *tm)
1.294 +@param tm
1.295 +
1.296 +Refer to ctime() for the documentation
1.297 +@see gettimeofday()
1.298 +@see getenv()
1.299 +@see time()
1.300 +@see tzset()
1.301 +
1.302 +
1.303 +
1.304 +
1.305 +@publishedAll
1.306 +@externallyDefinedApi
1.307 +*/
1.308 +
1.309 +/** @fn strftime(char * s, size_t maxsize, const char * format, const struct tm * t)
1.310 +@param s
1.311 +@param maxsize
1.312 +@param format
1.313 +@param t
1.314 +
1.315 +The strftime function formats the information from t into the buffer s according to the string pointed to by format .
1.316 +The format string consists of zero or more conversion specifications and
1.317 +ordinary characters.
1.318 +All ordinary characters are copied directly into the buffer.
1.319 +A conversion specification consists of a percent sign "\%"
1.320 +and one other character.
1.321 +
1.322 +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
1.323 +than maxsize , strftime returns the number of characters in the array, not counting
1.324 +the terminating NULL. Otherwise, zero is returned and the buffer contents are
1.325 +indeterminate.
1.326 +
1.327 +@code
1.328 +The conversion specifications are copied to the buffer after expansion as follows:-
1.329 +%A is replaced by national representation of the full weekday name.
1.330 +%a is replaced by national representation of the abbreviated weekday name.
1.331 +%B is replaced by national representation of the full month name.
1.332 +%b is replaced by national representation of the abbreviated month name.
1.333 +%C is replaced by (year / 100) as decimal number; single digits are preceded by a zero.
1.334 +%c is replaced by national representation of time and date.
1.335 +%D is equivalent to "%m/%d/%y".
1.336 +%d is replaced by the day of the month as a decimal number (01-31).
1.337 +%E* %O*
1.338 + 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.
1.339 +Additionally %OB implemented to represent alternative months names (used standalone, without day mentioned).
1.340 +
1.341 +%e is replaced by the day of month as a decimal number (1-31); single digits are preceded by a blank.
1.342 +%F is equivalent to "%Y-%m-%d".
1.343 +%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).
1.344 +%g is replaced by the same year as in "%G", but as a decimal number without century (00-99).
1.345 +%H is replaced by the hour (24-hour clock) as a decimal number (00-23).
1.346 +%h the same as %b.
1.347 +%I is replaced by the hour (12-hour clock) as a decimal number (01-12).
1.348 +%j is replaced by the day of the year as a decimal number (001-366).
1.349 +%k is replaced by the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank.
1.350 +%l is replaced by the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
1.351 +%M is replaced by the minute as a decimal number (00-59).
1.352 +%m is replaced by the month as a decimal number (01-12).
1.353 +%n is replaced by a newline.
1.354 +%O* the same as %E*.
1.355 +%p is replaced by national representation of either "ante meridiem" or "post meridiem" as appropriate.
1.356 +%R is equivalent to "%H:%M".
1.357 +%r is equivalent to "%I:%M:%S %p".
1.358 +%S is replaced by the second as a decimal number (00-60).
1.359 +%s is replaced by the number of seconds since the Epoch, UTC (see mktime).
1.360 +%T is equivalent to "%H:%M:%S".
1.361 +%t is replaced by a tab.
1.362 +%U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number (00-53).
1.363 +%u is replaced by the weekday (Monday as the first day of the week) as a decimal number (1-7).
1.364 +%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.
1.365 +%v is equivalent to "%e-%b-%Y".
1.366 +%W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number (00-53).
1.367 +%w is replaced by the weekday (Sunday as the first day of the week) as a decimal number (0-6).
1.368 +%X is replaced by national representation of the time.
1.369 +%x is replaced by national representation of the date.
1.370 +%Y is replaced by the year with century as a decimal number.
1.371 +%y is replaced by the year without century as a decimal number (00-99).
1.372 +%Z is replaced by the time zone name.
1.373 +%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).
1.374 +%+ is replaced by national representation of the date and time (the format is similar to that produced by 'date( )' function ).
1.375 +%-* GNU libc extension. Do not do any padding when performing numerical outputs.
1.376 +%_* GNU libc extension. Explicitly specify space for padding.
1.377 +%0* GNU libc extension. Explicitly specify zero for padding.
1.378 +%% is replaced by ‘%’.
1.379 +@endcode
1.380 +
1.381 +Examples:
1.382 +@code
1.383 +#include <string.h>
1.384 +#include <stdio.h>
1.385 +#include <time.h>
1.386 +#include <locale.h>
1.387 +int main()
1.388 +{
1.389 + struct tm tm;
1.390 + char buf[255];
1.391 + char *locale;
1.392 + locale = setlocale(LC_TIME,"en_GB.ISO-8859-1");
1.393 + if( locale != NULL)
1.394 + {
1.395 + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;);
1.396 + printf("sec = %d min = %d hours = %d
1.397 +Year = %d Month = %d day = %d
1.398 +",\
1.399 + tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday);
1.400 + strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;);
1.401 + puts(buf);
1.402 + strptime("Mon","%a", &tm;);
1.403 + strftime(buf, sizeof(buf), "%a", &tm;);
1.404 + puts(buf);
1.405 + }
1.406 + else
1.407 + printf("Failed to set locale
1.408 +");
1.409 +}
1.410 +
1.411 +@endcode
1.412 + Output
1.413 +@code
1.414 +sec = 1 min = 31 hours = 18
1.415 +Year = 101 Month = 10 day = 12
1.416 +12 November 2001 18:31:01
1.417 +Mon
1.418 +
1.419 +@endcode
1.420 +@see printf()
1.421 +@see ctime()
1.422 +@see strptime()
1.423 +@see wcsftime()
1.424 +
1.425 +
1.426 +
1.427 +
1.428 +@publishedAll
1.429 +@externallyDefinedApi
1.430 +*/
1.431 +
1.432 +/** @fn time(time_t *p)
1.433 +@param p
1.434 +@return On success the value of time in seconds since the Epoch is returned. On error
1.435 +(time_t)(-1) is returned and errno is set appropriately.
1.436 +
1.437 + The time function returns the value of time in seconds since 0 hours, 0
1.438 +minutes, 0 seconds, January 1, 1970, Coordinated Universal Time. If an error occurs, time returns the value ( time_t)(-1) .
1.439 +
1.440 + The return value is also stored in * p ,
1.441 +provided that p is non-null.
1.442 +
1.443 +Examples:
1.444 +@code
1.445 +/*
1.446 + * Detailed description : sample usage of time system call
1.447 + */
1.448 +#include <time.h>
1.449 +int main()
1.450 +{
1.451 + time_t Time ;
1.452 + if(time(&Time;) < 0 )
1.453 + {
1.454 + printf("Time system call failed
1.455 +") ;
1.456 + return -1 ;
1.457 + }
1.458 + printf("Time value is %u
1.459 +" , Time) ;
1.460 + return 0 ;
1.461 +}
1.462 +
1.463 +@endcode
1.464 + Output
1.465 +@code
1.466 +
1.467 +Time value is 1176916948
1.468 +
1.469 +@endcode
1.470 +@see gettimeofday()
1.471 +@see ctime()
1.472 +
1.473 +
1.474 +Bugs:
1.475 +
1.476 + Neither -isoC-99 nor -p1003.1-2001 requires time to set errno on failure; thus, it is impossible for an application to distinguish
1.477 +the valid time value -1 (representing the last UTC second of 1969)
1.478 +from the error return value.
1.479 +
1.480 +Systems conforming to earlier versions of the C and POSIX standards (including older versions of )
1.481 +did not set * p in the error case.
1.482 +
1.483 +
1.484 +@publishedAll
1.485 +@externallyDefinedApi
1.486 +*/
1.487 +
1.488 +/** @fn tzset(void)
1.489 +
1.490 + The tzset function
1.491 +initializes time conversion information used by the library routine localtime .
1.492 +The environment variable TZ specifies how this is done.
1.493 +
1.494 + If TZ does not appear in the environment, the best available approximation
1.495 + to local wall clock time is used.
1.496 +
1.497 + If TZ appears in the environment but its value is a null string, Coordinated
1.498 +Universal Time ( UTC )
1.499 +is used (without leap second correction).
1.500 +
1.501 +
1.502 +
1.503 +Examples:
1.504 +@code
1.505 +#include <time.h>
1.506 +#include <stdio.h>
1.507 +int main(){
1.508 + time_t t;
1.509 + char* c_time;
1.510 + tzset(); //Call tzset
1.511 + c_time = ctime (&t;); //Get time-string using ctime for Epoc time
1.512 + printf ("Time from ctime after tzset: %s", c_time);
1.513 + return 0;
1.514 +}
1.515 +
1.516 +@endcode
1.517 + Output
1.518 +@code
1.519 +Time from ctime after tzset: Sun Apr 7 02:24:08 1974
1.520 +
1.521 +@endcode
1.522 +@see gettimeofday()
1.523 +@see ctime()
1.524 +@see getenv()
1.525 +@see time()
1.526 +
1.527 +
1.528 +@see gettimeofday()
1.529 +@see ctime()
1.530 +@see getenv()
1.531 +@see time()
1.532 +@see gettimeofday()
1.533 +@see ctime()
1.534 +@see getenv()
1.535 +@see time()
1.536 +
1.537 +
1.538 +
1.539 +
1.540 +@publishedAll
1.541 +@externallyDefinedApi
1.542 +*/
1.543 +
1.544 +/** @fn clock_getres(clockid_t clock_id, struct timespec *res)
1.545 +@param clock_id
1.546 +@param res
1.547 +
1.548 +Refer to clock_gettime() for the documentation
1.549 +@see adjtime()
1.550 +@see ctime()
1.551 +
1.552 +
1.553 +
1.554 +
1.555 +@publishedAll
1.556 +@externallyDefinedApi
1.557 +*/
1.558 +
1.559 +/** @fn clock_gettime(clockid_t clock_id, struct timespec *tp)
1.560 +@param clock_id
1.561 +@param tp
1.562 +
1.563 +Note: This description also covers the following functions -
1.564 + clock_settime() clock_getres() clock_getcpuclockid()
1.565 +
1.566 +@return All the above APIs return 0 on success and -1 on failure.
1.567 +
1.568 +@code
1.569 + #include < sys/time.h > as:
1.570 +@endcode
1.571 + The clock_gettime and clock_settime allow the calling process to retrieve or set the value used by a clock
1.572 +which is specified by clock_id.
1.573 +
1.574 + The clock_id argument can be one of four values: CLOCK_REALTIME for time
1.575 + that increments as a wall clock should, CLOCK_MONOTONIC which increments in
1.576 + SI seconds, CLOCK_VIRTUAL for time that increments only when the CPU is running
1.577 + in user mode on behalf of the calling process, or CLOCK_PROF for time that increments
1.578 + when the CPU is running in user or kernel mode.
1.579 +
1.580 + As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
1.581 + is supported for all the clock-based APIs.
1.582 +
1.583 + The structure pointed to by tp is defined in
1.584 +@code
1.585 + #include <sys/time.h> as:
1.586 +@endcode
1.587 +
1.588 +@code
1.589 +struct timespec {
1.590 +time_ttv_sec;/* seconds */
1.591 +longtv_nsec;/* and nanoseconds */
1.592 +};
1.593 +@endcode
1.594 +
1.595 + The resolution (granularity) of a clock is returned by the clock_getres system call.
1.596 +This value is placed in a (non-NULL) *tp.
1.597 +
1.598 + The clock_getcpuclockid system call returns ( in *clock_id ) the clock ID of the CPU-time clock of the process specified
1.599 + by pid. If pid is zero, the clock ID of the CPU-time clock of the process making
1.600 + the call is returned.
1.601 +
1.602 +Examples:
1.603 +@code
1.604 +#include <time.h>
1.605 +#include <stdio.h>
1.606 +int clock_user()
1.607 +{
1.608 + struct timespec tp;
1.609 + int retval;
1.610 + clockid_t clockid;
1.611 + clock_getres (CLOCK_REALTIME, &tp;); // Call clock_getres
1.612 + printf ("Real time-clock resolution is %d seconds and %d nanoseconds
1.613 +", tp.tv_sec, tp.tv_nsec);
1.614 + clock_getcpuclockid (0 ,&clockid;); // Call clock_getcpuclockid with pid = 0
1.615 + printf ("The clock id for the current process is %d
1.616 +", clockid);
1.617 + tp.tv_sec = 0;
1.618 + tp.tv_nsec = 100;
1.619 + retval = clock_settime (CLOCK_REALTIME, &tp;); // Call clock_settime with 100ns
1.620 + printf ("clock_settime returned %d
1.621 +", retval);
1.622 + clock_gettime (CLOCK_REALTIME, &tp;); // Call clock_gettime to fill tp
1.623 + printf ("Time from real time-clock is %d seconds and %d nanoseconds
1.624 +", tp.tv_sec, tp.tv_nsec);
1.625 + return 0;
1.626 +}
1.627 +
1.628 +@endcode
1.629 + Output
1.630 +@code
1.631 +Real time-clock resolution is 0 seconds and 1000000 nanoseconds
1.632 +The clock id for the current process is 0
1.633 +clock_settime returned 0
1.634 +Time from real time-clock is 0 seconds and 70663000 nanoseconds
1.635 +
1.636 +@endcode
1.637 +@see adjtime()
1.638 +@see ctime()
1.639 +
1.640 +@publishedAll
1.641 +@externallyDefinedApi
1.642 +*/
1.643 +
1.644 +/** @fn clock_settime(clockid_t clock_id, const struct timespec *tp)
1.645 +@param clock_id
1.646 +@param tp
1.647 +
1.648 +Refer to clock_gettime() for the documentation
1.649 +
1.650 +@see adjtime()
1.651 +@see ctime()
1.652 +
1.653 +@capability Deferred @ref User::SetUTCTime(const TTime &aUTCTime)
1.654 +
1.655 +@publishedAll
1.656 +@externallyDefinedApi
1.657 +*/
1.658 +
1.659 +/** @fn nanosleep(const struct timespec *req, struct timespec *rem)
1.660 +@param req
1.661 +@param rem
1.662 +@return If the nanosleep system call returns because the requested time has elapsed, the value
1.663 +returned will be zero. If rem is non- NULL, the timespec structure it references is updated to contain the
1.664 +unslept amount (the request time minus the time actually slept).
1.665 +
1.666 + The nanosleep system call
1.667 +causes the process to sleep for the specified time.
1.668 +Currently only microsecond sleep resolution can be obtained.
1.669 +
1.670 +
1.671 +
1.672 +Examples:
1.673 +@code
1.674 +/*
1.675 + * Detailed description: Sample usage of nanosleep system call.
1.676 + */
1.677 +#include <stdio.h>
1.678 +#include <time.h>
1.679 +int main()
1.680 +{
1.681 + struct timespec tim, tim2;
1.682 + tim.tv_sec = 1;
1.683 + tim.tv_nsec = 500;
1.684 + if(nanosleep(&tim; , &tim2;) < 0 ) {
1.685 + printf("Nano sleep system call failed
1.686 +");
1.687 + return -1;
1.688 + }
1.689 + printf("Nano sleep successfull
1.690 +");
1.691 + return 0;
1.692 +}
1.693 +
1.694 +@endcode
1.695 + Output
1.696 +@code
1.697 +Nano sleep successfull
1.698 +
1.699 +@endcode
1.700 +@see sleep()
1.701 +
1.702 +
1.703 +
1.704 +
1.705 +@publishedAll
1.706 +@externallyDefinedApi
1.707 +*/
1.708 +
1.709 +/** @fn clock_getcpuclockid(pid_t pid, clockid_t* clock_id)
1.710 +@param pid
1.711 +@param clock_id
1.712 +
1.713 +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
1.714 + is supported for all the clock-based APIs. Any value for pid except "0" is considered as invalid
1.715 + and for "0" the supported 'clock_id' i.e, CLOCK_REALTIME is returned.
1.716 +
1.717 +Refer to clock_gettime() for the documentation
1.718 +@see adjtime()
1.719 +@see ctime()
1.720 +
1.721 +@publishedAll
1.722 +@externallyDefinedApi
1.723 +*/
1.724 +
1.725 +/** @fn clock_nanosleep (clockid_t clock_id, int flags,
1.726 + const struct timespec *rqtp, struct timespec *rmtp)
1.727 +@param clock_id
1.728 +@param flags
1.729 +@param rqtp
1.730 +@param rmtp
1.731 +
1.732 +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/clock_nanosleep.html
1.733 +
1.734 +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
1.735 + is supported for all the clock-based APIs.
1.736 +
1.737 +@publishedAll
1.738 +@externallyDefinedApi
1.739 +*/
1.740 +
1.741 +/** @fn asctime_r(const struct tm *tm, char *buf)
1.742 +@param tm
1.743 +@param buf
1.744 +
1.745 +Refer to ctime() for the documentation
1.746 +@see gettimeofday()
1.747 +@see getenv()
1.748 +@see time()
1.749 +@see tzset()
1.750 +
1.751 +
1.752 +
1.753 +
1.754 +@publishedAll
1.755 +@externallyDefinedApi
1.756 +*/
1.757 +
1.758 +/** @fn ctime_r(const time_t *clock, char *buf)
1.759 +@param clock
1.760 +@param buf
1.761 +
1.762 +Refer to ctime() for the documentation
1.763 +@see gettimeofday()
1.764 +@see getenv()
1.765 +@see time()
1.766 +@see tzset()
1.767 +
1.768 +
1.769 +
1.770 +
1.771 +@publishedAll
1.772 +@externallyDefinedApi
1.773 +*/
1.774 +
1.775 +/** @fn gmtime_r(const time_t *clock, struct tm *result)
1.776 +@param clock
1.777 +@param result
1.778 +
1.779 +Refer to ctime() for the documentation
1.780 +@see gettimeofday()
1.781 +@see getenv()
1.782 +@see time()
1.783 +@see tzset()
1.784 +
1.785 +
1.786 +
1.787 +
1.788 +@publishedAll
1.789 +@externallyDefinedApi
1.790 +*/
1.791 +
1.792 +
1.793 +/** @fn localtime_r(const time_t *clock, struct tm *result)
1.794 +@param clock
1.795 +@param result
1.796 +
1.797 +Refer to ctime() for the documentation
1.798 +@see gettimeofday()
1.799 +@see getenv()
1.800 +@see time()
1.801 +@see tzset()
1.802 +
1.803 +
1.804 +
1.805 +
1.806 +@publishedAll
1.807 +@externallyDefinedApi
1.808 +*/
1.809 +
1.810 +
1.811 +/** @fn strptime(const char * buf, const char * fmt, struct tm * tm)
1.812 +@param buf
1.813 +@param fmt
1.814 +@param tm
1.815 +@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 .
1.816 +It returns NULL if one of the conversions failed.
1.817 +
1.818 + The strptime function parses the string in the buffer buf according to the string pointed to by fmt ,
1.819 +and fills in the elements of the structure pointed to by tm .
1.820 +The resulting values will be relative to the local time zone.
1.821 +Thus, it can be considered the reverse operation of strftime .
1.822 +
1.823 + The fmt string consists of zero or more conversion specifications and
1.824 +ordinary characters.
1.825 +All ordinary characters are matched exactly with the buffer, where
1.826 +white space in the fmt string will match any amount of white space
1.827 +in the buffer.
1.828 +All conversion specifications are identical to those described in strftime .
1.829 +
1.830 + Two-digit year values, including formats \%y and \%D ,
1.831 +are now interpreted as beginning at 1969 per POSIX requirements.
1.832 +Years 69-00 are interpreted in the 20th century (1969-2000), years
1.833 +01-68 in the 21st century (2001-2068).
1.834 +
1.835 + If the fmt string does not contain enough conversion specifications to completely
1.836 +specify the resulting struct tm ,
1.837 +the unspecified members of tm are left untouched.
1.838 +For example, if format is "\%H:\%M:\%S",
1.839 +only tm_hour , tm_sec and tm_min will be modified.
1.840 +If time relative to today is desired, initialize the tm structure with today's date before passing it to strptime .
1.841 +
1.842 +Examples:
1.843 +@code
1.844 +#include <string.h>
1.845 +#include <stdio.h>
1.846 +#include <time.h>
1.847 +#include <locale.h>
1.848 +int main()
1.849 +{
1.850 + struct tm tm;
1.851 + char buf[255];
1.852 + char *locale;
1.853 + locale = setlocale(LC_TIME,"en_GB.ISO-8859-1");
1.854 + if( locale != NULL)
1.855 + {
1.856 + strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm;);
1.857 + printf("sec = %d min = %d hours = %d
1.858 +Year = %d Month = %d day = %d
1.859 +",
1.860 + tm.tm_sec,tm.tm_min,tm.tm_hour,tm.tm_year,tm.tm_mon,tm.tm_mday);
1.861 + strftime(buf, sizeof(buf), "%d %B %Y %H:%M:%S", &tm;);
1.862 + puts(buf);
1.863 + strptime("Mon","%a", &tm;);
1.864 + strftime(buf, sizeof(buf), "%a", &tm;);
1.865 + puts(buf);
1.866 + }
1.867 + else
1.868 + printf("Failed to set locale");
1.869 +}
1.870 +
1.871 +@endcode
1.872 + Output
1.873 +@code
1.874 +sec = 1 min = 31 hours = 18
1.875 +Year = 101 Month = 10 day = 12
1.876 +12 November 2001 18:31:01
1.877 +Mon
1.878 +
1.879 +@endcode
1.880 +@see scanf()
1.881 +@see strftime()
1.882 +
1.883 +
1.884 +Bugs:
1.885 +
1.886 + Both the \%e and \%l format specifiers may incorrectly scan one too many digits
1.887 +if the intended values comprise only a single digit
1.888 +and that digit is followed immediately by another digit.
1.889 +Both specifiers accept zero-padded values,
1.890 +even though they are both defined as taking unpadded values.
1.891 +
1.892 +The \%p format specifier has no effect unless it is parsed after hour-related specifiers.
1.893 +Specifying \%l without \%p will produce undefined results.
1.894 +Note that 12AM
1.895 +(ante meridiem)
1.896 +is taken as midnight
1.897 +and 12PM
1.898 +(post meridiem)
1.899 +is taken as noon.
1.900 +
1.901 +The \%U and \%W format specifiers accept any value within the range 00 to 53
1.902 +without validating against other values supplied (like month
1.903 +or day of the year, for example).
1.904 +
1.905 +The \%Z format specifier only accepts time zone abbreviations of the local time zone,
1.906 +or the value "GMT".
1.907 +This limitation is because of ambiguity due to of the over loading of time
1.908 +zone abbreviations.
1.909 +One such example is EST which is both Eastern Standard Time and Eastern Australia Summer Time.
1.910 +
1.911 +The strptime function does not correctly handle multibyte characters in the fmt argument.
1.912 +
1.913 +
1.914 +@publishedAll
1.915 +@externallyDefinedApi
1.916 +*/
1.917 +
1.918 +/** @fn timer_create (clockid_t __clock_id,
1.919 + struct sigevent *__restrict __evp,
1.920 + timer_t *__restrict __timerid)
1.921 +@param __clock_id
1.922 +@param __evp
1.923 +@param __timerid
1.924 +
1.925 +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_create.html
1.926 +
1.927 +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
1.928 + is supported for all the clock-based APIs.
1.929 +
1.930 +@see timer_settime()
1.931 +@see timer_delete()
1.932 +
1.933 +@publishedAll
1.934 +@externallyDefinedApi
1.935 +*/
1.936 +
1.937 +/** @fn timer_delete (timer_t __timerid)
1.938 +@param __timerid
1.939 +
1.940 +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_delete.html
1.941 +
1.942 +@see timer_create()
1.943 +@see timer_settime()
1.944 +
1.945 +@publishedAll
1.946 +@externallyDefinedApi
1.947 +*/
1.948 +
1.949 +/** @fn timer_settime(timer_t __timerid, int __flags,
1.950 + const struct itimerspec *__restrict __value,
1.951 + struct itimerspec *__restrict __ovalue)
1.952 +@param __timerid
1.953 +@param __flags
1.954 +@param __value
1.955 +@param __ovalue
1.956 +
1.957 +For full documentation, see http://www.opengroup.org/onlinepubs/009695399/functions/timer_settime.html
1.958 +
1.959 +Note: This description also covers the timer_gettime() and timer_getoverrun() functions.
1.960 +
1.961 +Note: As Symbian OS exposes only 'wall clock time' at user level, only CLOCK_REALTIME
1.962 + is supported for all the clock-based APIs. At the user level, Symbian OS supports upto a
1.963 + maximum of 1 ms resolution timer (RTimer::HighRes ()) upon which the timer emulation solution is based.
1.964 + As the re-registrations for a periodic timer happen in the user mode, the timer expirations
1.965 + might show up a possible unspecified latency.
1.966 +
1.967 +Examples:
1.968 +@code
1.969 +/*
1.970 + * Detailed description:
1.971 + */
1.972 +#include <time.h>
1.973 +#include <stdio.h>
1.974 +#include <signal.h>
1.975 +#include <pthread.h>
1.976 +#include <unistd.h>
1.977 +
1.978 +void sighler (union sigval val)
1.979 + {
1.980 + printf("In the handler with val:%d\n", val.sival_int);
1.981 + }
1.982 +
1.983 +int main()
1.984 + {
1.985 + timer_t timerid;
1.986 + struct sigevent sig;
1.987 +
1.988 + pthread_attr_t attr;
1.989 + pthread_attr_init( &attr );
1.990 +
1.991 + sig.sigev_notify = SIGEV_THREAD;
1.992 + sig.sigev_notify_function = sighler;
1.993 + sig.sigev_value.sival_int =20;
1.994 + sig.sigev_notify_attributes = &attr;
1.995 +
1.996 + if(0 == timer_create(CLOCK_REALTIME, &sig, &timerid))
1.997 + {
1.998 + struct itimerspec in, out;
1.999 +
1.1000 + in.it_value.tv_sec = 1;
1.1001 + in.it_value.tv_nsec = 0;
1.1002 +
1.1003 + in.it_interval.tv_sec = 0;
1.1004 + in.it_interval.tv_nsec = 0;
1.1005 +
1.1006 + if(0 == timer_settime(timerid, 0, &in, &out))
1.1007 + {
1.1008 + sleep(3); //wait for the timer expirations...
1.1009 + }
1.1010 + else
1.1011 + {
1.1012 + printf("timer_settime () failed with err:%d\n", errno);
1.1013 + }
1.1014 +
1.1015 + timer_delete(timerid);
1.1016 + }
1.1017 + else
1.1018 + {
1.1019 + printf("timer_create () failed with err:%d\n", errno);
1.1020 + }
1.1021 +
1.1022 + return 0;
1.1023 + }
1.1024 +
1.1025 +@endcode
1.1026 + Output
1.1027 +@code
1.1028 +In the handler with val:20
1.1029 +
1.1030 +@endcode
1.1031 +@see timer_create()
1.1032 +@see timer_delete()
1.1033 +@see clock_gettime()
1.1034 +
1.1035 +@publishedAll
1.1036 +@externallyDefinedApi
1.1037 +*/
1.1038 +
1.1039 +/** @fn timer_gettime (timer_t __timerid, struct itimerspec *__value)
1.1040 +@param __timerid
1.1041 +@param __value
1.1042 +
1.1043 +For documentation refer to timer_settime().
1.1044 +
1.1045 +@see timer_create()
1.1046 +@see timer_delete()
1.1047 +
1.1048 +@publishedAll
1.1049 +@externallyDefinedApi
1.1050 +*/
1.1051 +
1.1052 +/** @fn timer_getoverrun (timer_t __timerid)
1.1053 +@param __timerid
1.1054 +
1.1055 +For documentation refer to timer_settime().
1.1056 +
1.1057 +@see timer_create()
1.1058 +@see timer_delete()
1.1059 +
1.1060 +@publishedAll
1.1061 +@externallyDefinedApi
1.1062 +*/
1.1063 +
1.1064 +/** @def CLOCK_REALTIME
1.1065 +
1.1066 +This clock represents the realtime clock for the system.
1.1067 +
1.1068 +@publishedAll
1.1069 +@externallyDefinedApi
1.1070 +*/
1.1071 +
1.1072 +/** @def CLOCK_VIRTUAL
1.1073 +
1.1074 +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.
1.1075 +
1.1076 +@publishedAll
1.1077 +@externallyDefinedApi
1.1078 +*/
1.1079 +
1.1080 +/** @def TIMER_ABSTIME
1.1081 +
1.1082 +absolute timer
1.1083 +
1.1084 +@publishedAll
1.1085 +@externallyDefinedApi
1.1086 +*/
1.1087 +
1.1088 +/** @struct tm
1.1089 +
1.1090 +Contains the following members,
1.1091 +
1.1092 +@publishedAll
1.1093 +@externallyDefinedApi
1.1094 +*/
1.1095 +
1.1096 +/** @var tm::tm_sec
1.1097 +seconds after the minute
1.1098 +*/
1.1099 +
1.1100 +/** @var tm::tm_min
1.1101 +minutes after the hour
1.1102 +*/
1.1103 +
1.1104 +/** @var tm::tm_hour
1.1105 +hours since midnight
1.1106 +*/
1.1107 +
1.1108 +/** @var tm::tm_mday
1.1109 +day of the month
1.1110 +*/
1.1111 +
1.1112 +/** @var tm::tm_mon
1.1113 +months since January
1.1114 +*/
1.1115 +
1.1116 +/** @var tm::tm_year
1.1117 +years since 1900
1.1118 +*/
1.1119 +
1.1120 +/** @var tm::tm_wday
1.1121 +days since Sunday
1.1122 +*/
1.1123 +
1.1124 +/** @var tm::tm_yday
1.1125 +days since January 1
1.1126 +*/
1.1127 +
1.1128 +/** @var tm::tm_isdst
1.1129 +Daylight Savings Time flag
1.1130 +*/
1.1131 +
1.1132 +/** @var tm::tm_gmtoff
1.1133 +offset from UTC in seconds
1.1134 +*/
1.1135 +
1.1136 +/** @var tm::tm_zone
1.1137 +timezone abbreviation
1.1138 +*/
1.1139 +
1.1140 +
1.1141 +/** @fn time_t timegm(struct tm *tmp)
1.1142 +
1.1143 +@param tmp
1.1144 +
1.1145 +Description:
1.1146 +This function is inverses for gmtime.
1.1147 +Converts struct tm to time_t, assuming the data in tm is UTC rather than local timezone.
1.1148 +
1.1149 +@see gmtime()
1.1150 +@see localtime()
1.1151 +@see mktime()
1.1152 +@see tzset()
1.1153 +
1.1154 +@publishedAll
1.1155 +@externallyDefinedApi
1.1156 +*/