Changeset 087c8798 in mainline


Ignore:
Timestamp:
2011-07-20T19:30:30Z (14 years ago)
Author:
Petr Koupy <petr.koupy@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
102a729
Parents:
fc3680e
Message:

Added comments to stdlib.h functions (no change in functionality).

Location:
uspace/lib/posix
Files:
4 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/posix/stdlib.c

    rfc3680e r087c8798  
    3131 * @{
    3232 */
    33 /** @file
     33/** @file Standard library definitions.
    3434 */
    3535
    … …  
    5959
    6060/**
     61 * Integer absolute value.
    6162 *
    6263 * @param i Input value.
    … …  
    6970
    7071/**
     72 * Long integer absolute value.
    7173 *
    7274 * @param i Input value.
    … …  
    7981
    8082/**
     83 * Long long integer absolute value.
    8184 *
    8285 * @param i Input value.
    … …  
    8891}
    8992
     93/**
     94 * Compute the quotient and remainder of an integer division.
     95 *
     96 * @param numer Numerator.
     97 * @param denom Denominator.
     98 * @return Quotient and remainder packed into structure.
     99 */
    90100posix_div_t posix_div(int numer, int denom)
    91101{
    … …  
    93103}
    94104
     105/**
     106 * Compute the quotient and remainder of a long integer division.
     107 *
     108 * @param numer Numerator.
     109 * @param denom Denominator.
     110 * @return Quotient and remainder packed into structure.
     111 */
    95112posix_ldiv_t posix_ldiv(long numer, long denom)
    96113{
    … …  
    98115}
    99116
     117/**
     118 * Compute the quotient and remainder of a long long integer division.
     119 *
     120 * @param numer Numerator.
     121 * @param denom Denominator.
     122 * @return Quotient and remainder packed into structure.
     123 */
    100124posix_lldiv_t posix_lldiv(long long numer, long long denom)
    101125{
    … …  
    109133 * @param elem2 Second element to compare.
    110134 * @param compare Comparison function without userdata parameter.
    111  *
    112135 * @return Relative ordering of the elements.
    113136 */
    … …  
    121144 * Array sorting utilizing the quicksort algorithm.
    122145 *
    123  * @param array
    124  * @param count
    125  * @param size
    126  * @param compare
     146 * @param array Array of elements to sort.
     147 * @param count Number of elements in the array.
     148 * @param size Width of each element.
     149 * @param compare Decides relative ordering of two elements.
    127150 */
    128151void posix_qsort(void *array, size_t count, size_t size,
    … …  
    171194/**
    172195 * Retrieve a value of the given environment variable.
     196 *
    173197 * Since HelenOS doesn't support env variables at the moment,
    174198 * this function always returns NULL.
    175199 *
    176  * @param name
    177  * @return Always NULL.
     200 * @param name Name of the variable.
     201 * @return Value of the variable or NULL if such variable does not exist.
    178202 */
    179203char *posix_getenv(const char *name)
    … …  
    195219
    196220/**
    197  *
    198  * @param string String to be passed to a command interpreter.
    199  * @return
     221 * Issue a command.
     222 *
     223 * @param string String to be passed to a command interpreter or NULL.
     224 * @return Termination status of the command if the command is not NULL,
     225 *     otherwise indicate whether there is a command interpreter (non-zero)
     226 *     or not (zero).
    200227 */
    201228int posix_system(const char *string) {
    … …  
    205232
    206233/**
    207  *
    208  * @param name
    209  * @param resolved
    210  * @return
    211  */
    212 char *posix_realpath(const char *name, char *resolved)
     234 * Resolve absolute pathname.
     235 *
     236 * @param name Pathname to be resolved.
     237 * @param resolved Either buffer for the resolved absolute pathname or NULL.
     238 * @return On success, either resolved (if it was not NULL) or pointer to the
     239 *     newly allocated buffer containing the absolute pathname (if resolved was
     240 *     NULL). Otherwise NULL.
     241 *
     242 */
     243char *posix_realpath(const char *restrict name, char *restrict resolved)
    213244{
    214245        #ifndef PATH_MAX
    … …  
    254285 * its native representation. See posix_strtold().
    255286 *
    256  * @param nptr
    257  * @return
     287 * @param nptr String representation of a floating-point number.
     288 * @return Double-precision number resulting from the string conversion.
    258289 */
    259290double posix_atof(const char *nptr)
    … …  
    266297 * its native representation. See posix_strtold().
    267298 *
    268  * @param nptr
    269  * @param endptr
    270  * @return
     299 * @param nptr String representation of a floating-point number.
     300 * @param endptr Pointer to the final part of the string which
     301 *     was not used for conversion.
     302 * @return Single-precision number resulting from the string conversion.
    271303 */
    272304float posix_strtof(const char *restrict nptr, char **restrict endptr)
    … …  
    279311 * its native representation. See posix_strtold().
    280312 *
    281  * @param nptr
    282  * @param endptr
    283  * @return
     313 * @param nptr String representation of a floating-point number.
     314 * @param endptr Pointer to the final part of the string which
     315 *     was not used for conversion.
     316 * @return Double-precision number resulting from the string conversion.
    284317 */
    285318double posix_strtod(const char *restrict nptr, char **restrict endptr)
    … …  
    289322
    290323/**
    291  *
    292  * @param size
    293  * @return
     324 * Allocate memory chunk.
     325 *
     326 * @param size Size of the chunk to allocate.
     327 * @return Either pointer to the allocated chunk or NULL if not possible.
    294328 */
    295329void *posix_malloc(size_t size)
    … …  
    299333
    300334/**
    301  *
    302  * @param nelem
    303  * @param elsize
    304  * @return
     335 * Allocate memory for an array of elements.
     336 *
     337 * @param nelem Number of elements in the array.
     338 * @param elsize Size of each element.
     339 * @return Either pointer to the allocated array or NULL if not possible.
    305340 */
    306341void *posix_calloc(size_t nelem, size_t elsize)
    … …  
    310345
    311346/**
    312  *
    313  * @param ptr
    314  * @param size
    315  * @return
     347 * Reallocate memory chunk to a new size.
     348 *
     349 * @param ptr Memory chunk to reallocate. Might be NULL.
     350 * @param size Size of the reallocated chunk. Might be zero.
     351 * @return Either NULL or the pointer to the newly reallocated chunk.
    316352 */
    317353void *posix_realloc(void *ptr, size_t size)
    … …  
    321357
    322358/**
    323  *
    324  * @param ptr
     359 * Free allocated memory chunk.
     360 *
     361 * @param ptr Memory chunk to be freed.
    325362 */
    326363void posix_free(void *ptr)
    … …  
    343380
    344381/**
    345  * Should read system load statistics. Not supported. Always returns -1.
    346  *
    347  * @param loadavg
    348  * @param nelem
    349  * @return
     382 * Get system load average statistics.
     383 *
     384 * Not supported. Always returns -1.
     385 *
     386 * @param loadavg Array where the load averages shall be placed.
     387 * @param nelem Maximum number of elements to be placed into the array.
     388 * @return Number of elements placed into the array on success, -1 otherwise.
    350389 */
    351390int bsd_getloadavg(double loadavg[], int nelem)

  • uspace/lib/posix/stdlib.h

    rfc3680e r087c8798  
    3131 * @{
    3232 */
    33 /** @file
     33/** @file Standard library definitions.
    3434 */
    3535
    … …  
    5656extern long long posix_llabs(long long i);
    5757
    58 /* Integer division */
     58/* Integer Division */
    5959
    6060typedef struct {
    … …  
    8080    size_t nmemb, size_t size, int (*compar)(const void *, const void *));
    8181
    82 
    8382/* Environment Access */
    8483extern char *posix_getenv(const char *name);
    8584extern int posix_putenv(char *string);
    86 
    8785extern int posix_system(const char *string);
    88 
    8986
    9087/* Symbolic Links */
    … …  
    10198extern long int posix_atol(const char *nptr);
    10299extern long long int posix_atoll(const char *nptr);
    103 
    104100extern long int posix_strtol(const char *restrict nptr,
    105101    char **restrict endptr, int base);
    … …  
    110106extern unsigned long long int posix_strtoull(
    111107    const char *restrict nptr, char **restrict endptr, int base);
    112 
    113108
    114109/* Memory Allocation */

  • uspace/lib/posix/stdlib/strtol.c

    rfc3680e r087c8798  
    3030 * @{
    3131 */
    32 /** @file
     32/** @file Backend for integer conversions.
    3333 */
    3434
    … …  
    4242#include "../errno.h"
    4343
    44 // TODO: documentation
    45 
     44/**
     45 * Decides whether a digit belongs to a particular base.
     46 *
     47 * @param c Character representation of the digit.
     48 * @param base Base against which the digit shall be tested.
     49 * @return True if the digit belongs to the base, false otherwise.
     50 */
    4651static inline bool is_digit_in_base(int c, int base)
    4752{
    … …  
    5459}
    5560
     61/**
     62 * Derive a digit from its character representation.
     63 *
     64 * @param c Character representation of the digit.
     65 * @param base Base into which the digit belongs to.
     66 * @return Digit value represented by an integer.
     67 */
    5668static inline int get_digit_in_base(int c, int base)
    5769{
    … …  
    6375}
    6476
     77/**
     78 * Backend for all integer conversion functions. Can be configured by arguments
     79 * to convert both signed and unsigned integers of various sizes.
     80 *
     81 * @param nptr Input string.
     82 * @param endptr If non-NULL, *endptr is set to the position of the first
     83 *     unrecognized character.
     84 * @param base Expected base of the string representation.
     85 * @param min_value Lower bound for the resulting conversion.
     86 * @param max_value Upper bound for the resulting conversion.
     87 * @param out_negative Either NULL for unsigned conversion or a pointer to the
     88 *     bool variable into which shall be placed the negativity of the resulting
     89 *     converted value.
     90 * @return Result of the conversion.
     91 */
    6592static inline unsigned long long internal_strtol(
    6693    const char *restrict nptr, char **restrict endptr, int base,
    … …  
    188215}
    189216
     217/**
     218 * Convert a string to an integer.
     219 *
     220 * @param nptr Input string.
     221 * @return Result of the conversion.
     222 */
    190223int posix_atoi(const char *nptr)
    191224{
    … …  
    197230}
    198231
     232/**
     233 * Convert a string to a long integer.
     234 *
     235 * @param nptr Input string.
     236 * @return Result of the conversion.
     237 */
    199238long posix_atol(const char *nptr)
    200239{
    … …  
    206245}
    207246
     247/**
     248 * Convert a string to a long long integer.
     249 *
     250 * @param nptr Input string.
     251 * @return Result of the conversion.
     252 */
    208253long long posix_atoll(const char *nptr)
    209254{
    … …  
    215260}
    216261
     262/**
     263 * Convert a string to a long integer.
     264 *
     265 * @param nptr Input string.
     266 * @param endptr Pointer to the final part of the string which
     267 *     was not used for conversion.
     268 * @param base Expected base of the string representation.
     269 * @return Result of the conversion.
     270 */
    217271long posix_strtol(const char *restrict nptr, char **restrict endptr, int base)
    218272{
    … …  
    224278}
    225279
     280/**
     281 * Convert a string to a long long integer.
     282 *
     283 * @param nptr Input string.
     284 * @param endptr Pointer to the final part of the string which
     285 *     was not used for conversion.
     286 * @param base Expected base of the string representation.
     287 * @return Result of the conversion.
     288 */
    226289long long posix_strtoll(
    227290    const char *restrict nptr, char **restrict endptr, int base)
    … …  
    234297}
    235298
     299/**
     300 * Convert a string to an unsigned long integer.
     301 *
     302 * @param nptr Input string.
     303 * @param endptr Pointer to the final part of the string which
     304 *     was not used for conversion.
     305 * @param base Expected base of the string representation.
     306 * @return Result of the conversion.
     307 */
    236308unsigned long posix_strtoul(
    237309    const char *restrict nptr, char **restrict endptr, int base)
    … …  
    243315}
    244316
     317/**
     318 * Convert a string to a an unsigned long long integer.
     319 *
     320 * @param nptr Input string.
     321 * @param endptr Pointer to the final part of the string which
     322 *     was not used for conversion.
     323 * @param base Expected base of the string representation.
     324 * @return Result of the conversion.
     325 */
    245326unsigned long long posix_strtoull(
    246327    const char *restrict nptr, char **restrict endptr, int base)
    … …  
    249330}
    250331
    251 
    252332/** @}
    253333 */
    254 

  • uspace/lib/posix/stdlib/strtold.c

    rfc3680e r087c8798  
    3030 * @{
    3131 */
    32 /** @file
     32/** @file Backend for floating point conversions.
    3333 */
    3434
    … …  
    5555#endif
    5656
    57 // TODO: clean up, documentation
     57// TODO: clean up
    5858
    5959// FIXME: ensure it builds and works on all platforms
    … …  
    116116};
    117117
     118/**
     119 * Decides whether the argument is still in range representable by
     120 * long double or not.
     121 *
     122 * @param num Floating point number to be checked.
     123 * @return True if the argument is out of range, false otherwise.
     124 */
    118125static inline bool out_of_range(long double num)
    119126{
    … …  
    127134 * @param base Number to be multiplied.
    128135 * @param exponent Base 5 exponent.
    129  * @return base multiplied by 5**exponent
     136 * @return base multiplied by 5**exponent.
    130137 */
    131138static long double mul_pow5(long double base, int exponent)
    … …  
    173180 * @param base Number to be multiplied.
    174181 * @param exponent Base 2 exponent.
    175  * @return base multiplied by 2**exponent
     182 * @return base multiplied by 2**exponent.
    176183 */
    177184static long double mul_pow2(long double base, int exponent)
    … …  
    212219}
    213220
    214 
     221/**
     222 * Convert decimal string representation of the floating point number.
     223 * Function expects the string pointer to be already pointed at the first
     224 * digit (i.e. leading optional sign was already consumed by the caller).
     225 *
     226 * @param sptr Pointer to the storage of the string pointer. Upon successful
     227 *     conversion, the string pointer is updated to point to the first
     228 *     unrecognized character.
     229 * @return An approximate representation of the input floating-point number.
     230 */
    215231static long double parse_decimal(const char **sptr)
    216232{
    … …  
    315331}
    316332
     333/**
     334 * Derive a hexadecimal digit from its character representation.
     335 *
     336 * @param ch Character representation of the hexadecimal digit.
     337 * @return Digit value represented by an integer.
     338 */
    317339static inline int hex_value(char ch)
    318340{
    … …  
    325347
    326348/**
     349 * Get the count of leading zero bits up to the maximum of 3 zero bits.
     350 *
    327351 * @param val Integer value.
    328352 * @return How many leading zero bits there are. (Maximum is 3)
    … …  
    339363}
    340364
     365/**
     366 * Convert hexadecimal string representation of the floating point number.
     367 * Function expects the string pointer to be already pointed at the first
     368 * digit (i.e. leading optional sign and 0x prefix were already consumed
     369 * by the caller).
     370 *
     371 * @param sptr Pointer to the storage of the string pointer. Upon successful
     372 *     conversion, the string pointer is updated to point to the first
     373 *     unrecognized character.
     374 * @return Representation of the input floating-point number.
     375 */
    341376static long double parse_hexadecimal(const char **sptr)
    342377{
    … …  
    567602/** @}
    568603 */
    569 
Note: See TracChangeset for help on using the changeset viewer.