Changeset 55b1efd in mainline for uspace/lib/posix/time.c


Ignore:
Timestamp:
2011-08-17T19:56:14Z (13 years ago)
Author:
Petr Koupy <petr.koupy@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
6921178
Parents:
e6165be
Message:

Minor corrections and unifications of the recently added documentation.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/posix/time.c

    re6165be r55b1efd  
    5151#include "libc/sys/time.h"
    5252
    53 // TODO: documentation
    5453// TODO: test everything in this file
    5554
    … …  
    7271#define SECS_PER_DAY (SECS_PER_HOUR * HOURS_PER_DAY)
    7372
    74 /** Checks whether the year is a leap year.
     73/**
     74 * Checks whether the year is a leap year.
    7575 *
    7676 * @param year Year since 1900 (e.g. for 1970, the value is 70).
    … …  
    9090}
    9191
    92 /** Returns how many days there are in the given month of the given year.
    93  *  Note that year is only taken into account if month is February.
     92/**
     93 * Returns how many days there are in the given month of the given year.
     94 * Note that year is only taken into account if month is February.
    9495 *
    9596 * @param year Year since 1900 (can be negative).
    … …  
    113114}
    114115
    115 /** For specified year, month and day of month, returns which day of that year
    116  *  it is.
     116/**
     117 * For specified year, month and day of month, returns which day of that year
     118 * it is.
    117119 *
    118120 * For example, given date 2011-01-03, the corresponding expression is:
    … …  
    134136}
    135137
    136 /** Integer division that rounds to negative infinity.
    137  *  Used by some functions in this file.
    138  *
    139  * @param op1
    140  * @param op2
    141  * @return
     138/**
     139 * Integer division that rounds to negative infinity.
     140 * Used by some functions in this file.
     141 *
     142 * @param op1 Divident.
     143 * @param op2 Divisor.
     144 * @return Rounded quotient.
    142145 */
    143146static time_t _floor_div(time_t op1, time_t op2)
    … …  
    150153}
    151154
    152 /** Modulo that rounds to negative infinity.
    153  *  Used by some functions in this file.
    154  *
    155  * @param op1
    156  * @param op2
    157  * @return
     155/**
     156 * Modulo that rounds to negative infinity.
     157 * Used by some functions in this file.
     158 *
     159 * @param op1 Divident.
     160 * @param op2 Divisor.
     161 * @return Remainder.
    158162 */
    159163static time_t _floor_mod(time_t op1, time_t op2)
    … …  
    174178}
    175179
    176 /** Number of days since the Epoch.
    177  *  Epoch is 1970-01-01, which is also equal to day 0.
     180/**
     181 * Number of days since the Epoch.
     182 * Epoch is 1970-01-01, which is also equal to day 0.
    178183 *
    179184 * @param year Year (year 1900 = 0, may be negative).
    … …  
    189194}
    190195
    191 /** Seconds since the Epoch. see also _days_since_epoch().
     196/**
     197 * Seconds since the Epoch. see also _days_since_epoch().
    192198 *
    193199 * @param tm Normalized broken-down time.
    … …  
    201207}
    202208
    203 /** Which day of week the specified date is.
     209/**
     210 * Which day of week the specified date is.
    204211 *
    205212 * @param year Year (year 1900 = 0).
    … …  
    214221}
    215222
    216 /** Normalizes the broken-down time and optionally adds specified amount of
    217  *  seconds.
     223/**
     224 * Normalizes the broken-down time and optionally adds specified amount of
     225 * seconds.
    218226 *
    219227 * @param tm Broken-down time to normalize.
    … …  
    297305}
    298306
    299 /** Which day the week-based year starts on, relative to the first calendar day.
    300  *  E.g. if the year starts on December 31st, the return value is -1.
     307/**
     308 * Which day the week-based year starts on, relative to the first calendar day.
     309 * E.g. if the year starts on December 31st, the return value is -1.
    301310 *
    302311 * @param Year since 1900.
    … …  
    309318}
    310319
    311 /** Returns week-based year of the specified time.
     320/**
     321 * Returns week-based year of the specified time.
    312322 *
    313323 * @param tm Normalized broken-down time.
    … …  
    329339}
    330340
    331 /** Week number of the year, assuming weeks start on sunday.
    332  *  The first Sunday of January is the first day of week 1;
    333  *  days in the new year before this are in week 0.
     341/**
     342 * Week number of the year, assuming weeks start on sunday.
     343 * The first Sunday of January is the first day of week 1;
     344 * days in the new year before this are in week 0.
    334345 *
    335346 * @param tm Normalized broken-down time.
    … …  
    342353}
    343354
    344 /** Week number of the year, assuming weeks start on monday.
    345  *  If the week containing January 1st has four or more days in the new year,
    346  *  then it is considered week 1. Otherwise, it is the last week of the previous
    347  *  year, and the next week is week 1. Both January 4th and the first Thursday
    348  *  of January are always in week 1.
     355/**
     356 * Week number of the year, assuming weeks start on monday.
     357 * If the week containing January 1st has four or more days in the new year,
     358 * then it is considered week 1. Otherwise, it is the last week of the previous
     359 * year, and the next week is week 1. Both January 4th and the first Thursday
     360 * of January are always in week 1.
    349361 *
    350362 * @param tm Normalized broken-down time.
    … …  
    366378}
    367379
    368 /** Week number of the year, assuming weeks start on monday.
    369  *  The first Monday of January is the first day of week 1;
    370  *  days in the new year before this are in week 0.
     380/**
     381 * Week number of the year, assuming weeks start on monday.
     382 * The first Monday of January is the first day of week 1;
     383 * days in the new year before this are in week 0.
    371384 *
    372385 * @param tm Normalized broken-down time.
    … …  
    385398char *posix_tzname[2];
    386399
    387 /** Set timezone conversion information.
    388  *
     400/**
     401 * Set timezone conversion information.
    389402 */
    390403void posix_tzset(void)
    … …  
    397410}
    398411
    399 /** Calculate the difference between two times, in seconds.
    400  *
    401  * @param time1
    402  * @param time0
     412/**
     413 * Calculate the difference between two times, in seconds.
     414 *
     415 * @param time1 First time.
     416 * @param time0 Second time.
    403417 * @return Time in seconds.
    404418 */
    … …  
    408422}
    409423
    410 /** This function first normalizes the provided broken-down time
    411  *  (moves all values to their proper bounds) and then tries to
    412  *  calculate the appropriate time_t representation.
     424/**
     425 * This function first normalizes the provided broken-down time
     426 * (moves all values to their proper bounds) and then tries to
     427 * calculate the appropriate time_t representation.
    413428 *
    414429 * @param tm Broken-down time.
    415  * @return time_t representation of the time, undefined value on overflow
     430 * @return time_t representation of the time, undefined value on overflow.
    416431 */
    417432time_t posix_mktime(struct posix_tm *tm)
    … …  
    424439}
    425440
    426 /** Converts a time value to a broken-down UTC time.
     441/**
     442 * Converts a time value to a broken-down UTC time.
    427443 *
    428444 * @param timer Time to convert.
    … …  
    437453}
    438454
    439 /** Converts a time value to a broken-down UTC time.
     455/**
     456 * Converts a time value to a broken-down UTC time.
    440457 *
    441458 * @param timer Time to convert.
    … …  
    465482}
    466483
    467 /** Converts a time value to a broken-down local time.
     484/**
     485 * Converts a time value to a broken-down local time.
    468486 *
    469487 * @param timer Time to convert.
    … …  
    476494}
    477495
    478 /** Converts a time value to a broken-down local time.
     496/**
     497 * Converts a time value to a broken-down local time.
    479498 *
    480499 * @param timer Time to convert.
    … …  
    490509}
    491510
    492 /** Converts broken-down time to a string in format
    493  *  "Sun Jan 1 00:00:00 1970\n". (Obsolete)
     511/**
     512 * Converts broken-down time to a string in format
     513 * "Sun Jan 1 00:00:00 1970\n". (Obsolete)
    494514 *
    495515 * @param timeptr Broken-down time structure.
    … …  
    502522}
    503523
    504 /** Converts broken-down time to a string in format
    505  *  "Sun Jan 1 00:00:00 1970\n". (Obsolete)
     524/**
     525 * Converts broken-down time to a string in format
     526 * "Sun Jan 1 00:00:00 1970\n". (Obsolete)
    506527 *
    507528 * @param timeptr Broken-down time structure.
    … …  
    534555}
    535556
    536 /** Equivalent to asctime(localtime(clock)).
     557/**
     558 * Equivalent to asctime(localtime(clock)).
    537559 *
    538560 * @param timer Time to convert.
    … …  
    548570}
    549571
    550 /** Reentrant variant of ctime().
     572/**
     573 * Reentrant variant of ctime().
    551574 *
    552575 * @param timer Time to convert.
    … …  
    564587}
    565588
    566 /** Convert time and date to a string, based on a specified format and
    567  *  current locale.
     589/**
     590 * Convert time and date to a string, based on a specified format and
     591 * current locale.
    568592 *
    569593 * @param s Buffer to write string to.
    … …  
    755779}
    756780
    757 /** Get clock resolution. Only CLOCK_REALTIME is supported.
     781/**
     782 * Get clock resolution. Only CLOCK_REALTIME is supported.
    758783 *
    759784 * @param clock_id Clock ID.
    … …  
    776801}
    777802
    778 /** Get time. Only CLOCK_REALTIME is supported.
     803/**
     804 * Get time. Only CLOCK_REALTIME is supported.
    779805 *
    780806 * @param clock_id ID of the clock to query.
    781807 * @param tp Pointer to the variable where the time is to be written.
    782  * @return
     808 * @return 0 on success, -1 with errno on failure.
    783809 */
    784810int posix_clock_gettime(posix_clockid_t clock_id, struct posix_timespec *tp)
    … …  
    800826}
    801827
    802 /** Set time on a specified clock. As HelenOS doesn't support this yet,
    803  *  this function always fails.
     828/**
     829 * Set time on a specified clock. As HelenOS doesn't support this yet,
     830 * this function always fails.
    804831 *
    805832 * @param clock_id ID of the clock to set.
    … …  
    825852}
    826853
    827 /** Sleep on a specified clock.
     854/**
     855 * Sleep on a specified clock.
    828856 *
    829857 * @param clock_id ID of the clock to sleep on (only CLOCK_REALTIME supported).
    … …  
    855883}
    856884
    857 /** Get CPU time used since the process invocation.
     885/**
     886 * Get CPU time used since the process invocation.
    858887 *
    859888 * @return Consumed CPU cycles by this process or -1 if not available.
Note: See TracChangeset for help on using the changeset viewer.