Changeset 55b1efd in mainline


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.

Location:
uspace/lib/posix
Files:
6 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/posix/fnmatch.c

    re6165be r55b1efd  
    6666#define COLL_ELM_INVALID -1
    6767
    68 /** Get collating element matching a string.
    69  *
    70  * @param str
     68/**
     69 * Get collating element matching a string.
     70 *
     71 * @param str String representation of the element.
    7172 * @return Matching collating element or COLL_ELM_INVALID.
    7273 */
    … …  
    7980}
    8081
    81 /** Get collating element matching a single character.
    82  *
    83  * @param c
    84  * @return
     82/**
     83 * Get collating element matching a single character.
     84 *
     85 * @param c Character representation of the element.
     86 * @return Matching collating element.
    8587 */
    8688static coll_elm_t _coll_elm_char(int c)
    … …  
    8991}
    9092
    91 /** Match collating element with a beginning of a string.
    92  *
    93  * @param elm
    94  * @param str
     93/**
     94 * Match collating element with a beginning of a string.
     95 *
     96 * @param elm Collating element to match.
     97 * @param str String which beginning should match the element.
    9598 * @return 0 if the element doesn't match, or the number of characters matched.
    9699 */
    … …  
    100103}
    101104
    102 /** Checks whether a string begins with a collating element in the given range.
    103  *  Ordering depends on the locale (if locales are supported).
     105/**
     106 * Checks whether a string begins with a collating element in the given range.
     107 * Ordering depends on the locale (if locales are supported).
    104108 *
    105109 * @param first First element of the range.
    … …  
    114118}
    115119
    116 /** Read a string delimited by [? and ?].
     120/**
     121 * Read a string delimited by [? and ?].
    117122 *
    118123 * @param pattern Pointer to the string to read from. Its position is moved
    … …  
    189194};
    190195
    191 /** Compare function for binary search in the _char_classes array.
     196/**
     197 * Compare function for binary search in the _char_classes array.
    192198 *
    193  * @param key
    194  * @param elem
    195  * @return
     199 * @param key Key of the searched element.
     200 * @param elem Element of _char_classes array.
     201 * @return Ordering indicator (-1 less than, 0 equal, 1 greater than).
    196202 */
    197203static int _class_compare(const void *key, const void *elem)
    … …  
    201207}
    202208
    203 /** Returns whether the given character belongs to the specified character class.
     209/**
     210 * Returns whether the given character belongs to the specified character class.
    204211 *
    205212 * @param cname Name of the character class.
    … …  
    223230}
    224231
    225 /** Tries to parse an initial part of the pattern as a character class pattern,
    226  *  and if successful, matches the beginning of the given string against the class.
     232/**
     233 * Tries to parse an initial part of the pattern as a character class pattern,
     234 * and if successful, matches the beginning of the given string against the class.
    227235 *
    228236 * @param pattern Pointer to the pattern to match. Must begin with a class
    … …  
    248256/************** END CHARACTER CLASSES ****************/
    249257
    250 /** Reads the next collating element in the pattern, taking into account
    251  *  locale (if supported) and flags (see fnmatch()).
     258/**
     259 * Reads the next collating element in the pattern, taking into account
     260 * locale (if supported) and flags (see fnmatch()).
    252261 *
    253262 * @param pattern Pattern.
    … …  
    299308}
    300309
    301 /** Matches the beginning of the given string against a bracket expression
    302  *  the pattern begins with.
     310/**
     311 * Matches the beginning of the given string against a bracket expression
     312 * the pattern begins with.
    303313 *
    304314 * @param pattern Pointer to the beginning of a bracket expression in a pattern.
    … …  
    394404}
    395405
    396 /** Matches a portion of the pattern containing no asterisks (*) against
    397  *  the given string.
     406/**
     407 * Matches a portion of the pattern containing no asterisks (*) against
     408 * the given string.
    398409 *
    399410 * @param pattern Pointer to the unmatched portion of the pattern.
    … …  
    497508}
    498509
    499 /** Match string against a pattern.
     510/**
     511 * Match string against a pattern.
    500512 *
    501513 * @param pattern Pattern.
    … …  
    559571}
    560572
    561 /** Transform the entire string to lowercase.
     573/**
     574 * Transform the entire string to lowercase.
    562575 *
    563576 * @param s Input string.
    … …  
    578591 * Filename pattern matching.
    579592 *
    580  * @param pattern
    581  * @param string
    582  * @param flags
    583  * @return
     593 * @param pattern Pattern to match the string against.
     594 * @param string Matched string.
     595 * @param flags Flags altering the matching of special characters
     596 *     (mainly for dot and slash).
     597 * @return Zero if the string matches the pattern, FNM_NOMATCH otherwise.
    584598 */
    585599int posix_fnmatch(const char *pattern, const char *string, int flags)

  • uspace/lib/posix/locale.c

    re6165be r55b1efd  
    7979};
    8080
    81 /** Set program locale.
     81/**
     82 * Set program locale.
    8283 *
    8384 * @param category What category to set.
    … …  
    9596}
    9697
    97 /** Return locale-specific information.
     98/**
     99 * Return locale-specific information.
    98100 *
    99101 * @return Information about the current locale.
    … …  
    105107}
    106108
    107 /** Duplicate locale object.
     109/**
     110 * Duplicate locale object.
    108111 *
    109112 * @param locobj Object to duplicate.
    … …  
    125128}
    126129
    127 /** Free locale object.
     130/**
     131 * Free locale object.
    128132 *
    129133 * @param locobj Object to free.
    … …  
    136140}
    137141
    138 /** Create or modify a locale object.
     142/**
     143 * Create or modify a locale object.
    139144 *
    140145 * @param category_mask Mask of categories to be set or modified.
    … …  
    163168}
    164169
    165 /** Set locale for the current thread.
     170/**
     171 * Set locale for the current thread.
    166172 *
    167173 * @param newloc Locale to use.

  • uspace/lib/posix/signal.c

    re6165be r55b1efd  
    136136}
    137137
    138 /** Just an empty function to get an unique pointer value for comparison.
    139  *
    140  * @param signo
     138/**
     139 * Just an empty function to get an unique pointer value for comparison.
     140 *
     141 * @param signo Signal number.
    141142 */
    142143void __posix_hold_signal_handler(int signo)
    … …  
    145146}
    146147
    147 /** Empty function to be used as ignoring handler.
    148  *
    149  * @param signo
     148/**
     149 * Empty function to be used as ignoring handler.
     150 *
     151 * @param signo Signal number.
    150152 */
    151153void __posix_ignore_signal_handler(int signo)
    … …  
    154156}
    155157
    156 /** Clear the signal set.
     158/**
     159 * Clear the signal set.
    157160 *
    158161 * @param set Pointer to the signal set.
    … …  
    167170}
    168171
    169 /** Fill the signal set (i.e. add all signals).
     172/**
     173 * Fill the signal set (i.e. add all signals).
    170174 *
    171175 * @param set Pointer to the signal set.
    … …  
    180184}
    181185
    182 /** Add a signal to the set.
     186/**
     187 * Add a signal to the set.
    183188 *
    184189 * @param set Pointer to the signal set.
    … …  
    194199}
    195200
    196 /** Delete a signal from the set.
     201/**
     202 * Delete a signal from the set.
    197203 *
    198204 * @param set Pointer to the signal set.
    … …  
    208214}
    209215
    210 /** Inclusion test for a signal set.
     216/**
     217 * Inclusion test for a signal set.
    211218 *
    212219 * @param set Pointer to the signal set.
    … …  
    221228}
    222229
    223 /** Unsafe variant of the sigaction() function.
    224  *  Doesn't do any checking of its arguments and
    225  *  does not deal with thread-safety.
     230/**
     231 * Unsafe variant of the sigaction() function.
     232 * Doesn't do any checking of its arguments and
     233 * does not deal with thread-safety.
    226234 *
    227235 * @param sig
    … …  
    243251}
    244252
    245 /** Sets a new action for the given signal number.
     253/**
     254 * Sets a new action for the given signal number.
    246255 *
    247256 * @param sig Signal number to set action for.
    … …  
    276285}
    277286
    278 /** Sets a new handler for the given signal number.
     287/**
     288 * Sets a new handler for the given signal number.
    279289 *
    280290 * @param sig Signal number to set handler for.
    … …  
    304314} signal_queue_item;
    305315
    306 /** Queue blocked signal.
     316/**
     317 * Queue blocked signal.
    307318 *
    308319 * @param signo Signal number.
    … …  
    322333
    323334
    324 /** Executes an action associated with the given signal.
     335/**
     336 * Executes an action associated with the given signal.
    325337 *
    326338 * @param signo Signal number.
    … …  
    366378}
    367379
    368 /** Raise all unblocked previously queued signals.
     380/**
     381 * Raise all unblocked previously queued signals.
    369382 */
    370383static void _dequeue_unblocked_signals()
    … …  
    390403}
    391404
    392 /** Raise a signal for the calling process.
     405/**
     406 * Raise a signal for the calling process.
    393407 *
    394408 * @param sig Signal number.
    … …  
    409423}
    410424
    411 /** Raises a signal for a selected process.
     425/**
     426 * Raises a signal for a selected process.
    412427 *
    413428 * @param pid PID of the process for which the signal shall be raised.
    … …  
    446461}
    447462
    448 /** Send a signal to a process group. Always fails at the moment because of
    449  *  lack of this functionality in HelenOS.
     463/**
     464 * Send a signal to a process group. Always fails at the moment because of
     465 * lack of this functionality in HelenOS.
    450466 *
    451467 * @param pid PID of the process group.
    … …  
    459475}
    460476
    461 /** Outputs information about the signal to the standard error stream.
     477/**
     478 * Outputs information about the signal to the standard error stream.
    462479 *
    463480 * @param pinfo SigInfo struct to write.
    … …  
    471488}
    472489
    473 /** Outputs information about the signal to the standard error stream.
     490/**
     491 * Outputs information about the signal to the standard error stream.
    474492 *
    475493 * @param signum Signal number.
    … …  
    486504}
    487505
    488 /** Manipulate the signal mask of the calling thread.
     506/**
     507 * Manipulate the signal mask of the calling thread.
    489508 *
    490509 * @param how What to do with the mask.
    … …  
    525544}
    526545
    527 /** Manipulate the signal mask of the process.
     546/**
     547 * Manipulate the signal mask of the process.
    528548 *
    529549 * @param how What to do with the mask.

  • uspace/lib/posix/stdio.h

    re6165be r55b1efd  
    140140
    141141        #define freopen posix_freopen
    142         #define fmemopen posix_fmemopen
    143         #define open_memstream posix_open_memstream
    144142
    145143        #define perror posix_perror

  • 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.

  • uspace/lib/posix/time.h

    re6165be r55b1efd  
    162162        #define clock_settime posix_clock_settime
    163163        #define clock_nanosleep posix_clock_nanosleep
    164        
    165         #define timer_create posix_timer_create
    166         #define timer_delete posix_timer_delete
    167         #define timer_getoverrun posix_timer_getoverrun
    168         #define timer_gettime posix_timer_gettime
    169         #define timer_settime posix_timer_settime
    170        
     164
    171165        #define clock posix_clock
    172166#endif
Note: See TracChangeset for help on using the changeset viewer.