IAR C LIBRARY FUNCTIONS Reference Guide IARCLIB-1 COPYRIGHT NOTICE © Copyright 2000 IAR Systems. All rights reserved. No part of this document may be reproduced without the prior written consent of IAR Systems. The software described in this document is furnished under a license and may only be used or copied in accordance with the terms of such a license. DISCLAIMER The information in this document is subject to change without notice and does not represent a commitment on any part of IAR Systems. While the information contained herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors or omissions. In no event shall IAR Systems, its employees, its contractors, or the authors of this document be liable for special, direct, indirect, or consequential damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind. TRADEMARKS IAR and C-SPY are registered trademarks of IAR Systems. IAR Embedded Workbench, IAR XLINK Linker, and IAR XLIB Librarian are trademarks of IAR Systems. Microsoft is a registered trademark, and Windows is a trademark of Microsoft Corporation. All other product names are trademarks or registered trademarks of their respective owners. EDITION NOTICE First edition: September 2000 Part number: IARCLIB-1 IAR C Library Functions ii Reference Guide IARCLIB-1 C library functions reference This guide gives an alphabetical list of the C library functions, including afull description of their operation and options available for eachone. Descriptions of C library functions Each function description contains the following information: (cid:1) Function name The name of the C library function. (cid:1) Declaration The C library declaration. (cid:1) Parameters Details of each parameter in the declaration. (cid:1) Return value The value, if any, returned by the function. (cid:1) Description A detailed description covering the function’s most general use. This includes information about what the function is useful for, and a discussion of any special conditions and common pitfalls. (cid:1) Header filename The function header filename. (cid:1) Examples One or more examples illustrating how the function can be used. The following sections contain full reference information for each C library function. abort void abort(void) Parameters None. Return value None. 1 IARCLIB-1 Descriptions of C library functions Description Terminates the program abnormally and does not return to the caller. This function calls the funciton exit, and by default the entry for this resides in CSTARTUP. Header file stdlib.h abs int abs(int j) Parameters j An int value. Return value An int having the absolute value of j. Description Computes the absolute value of j. Header file stdlib.h acos double acos(double arg) Parameters arg A double in the range [-1,+1]. Return value The double arc cosine of arg, in the range [0,pi]. Description Computes the principal value in radians of the arc cosine of arg. Header file math.h IAR C Library Functions 2 Reference Guide IARCLIB-1 C library functions reference asin double asin(double arg) Parameters arg A double in the range [-1,+1]. Return value The double arc sine of arg, in the range [-pi/2,+pi/2]. Description Computes the principal value in radians of the arc sine of arg. Header file math.h assert void assert (int expression) Parameters expression An expression to be checked. Return value None. Description This is a macro that checks an expression. If it is false it prints a message to stderr and calls abort. The message has the following format: File name; line num # Assertion failure "expression" To ignore assert calls put a #define NDEBUG statement before the #include <assert.h> statement. Header file assert.h 3 IARCLIB-1 Descriptions of C library functions atan double atan(double arg) Parameters arg A double value. Return value The double arc tangent of arg, in the range [-pi/2,pi/2]. Description Computes the arc tangent of arg. Header file math.h atan2 double atan2(double arg1, double arg2) Parameters arg1 A double value. arg2 A double value. Return value The double arc tangent of arg1/arg2, in the range [-pi,pi]. Description Computes the arc tangent of arg1/arg2, using the signs of both arguments to determine the quadrant of the return value. Header file math.h atof double atof(const char *nptr) Parameters nptr A pointer to a string containing a number in ASCII form. IAR C Library Functions 4 Reference Guide IARCLIB-1 C library functions reference Return value The double number found in the string. Description Converts the string pointed to by nptr to a double-precision floating-point number, skipping white space and terminating upon reaching any unrecognized character. Header file stdlib.h Examples " -3K" gives -3.00 ".0006" gives 0.0006 "1e-4" gives 0.0001 atoi int atoi(const char *nptr) Parameters nptr A pointer to a string containing a number in ASCII form. Return value The int number found in the string. Description Converts the ASCII string pointed to by nptr to an integer, skipping white space and terminating upon reaching any unrecognized character. Header file stdlib.h Examples " -3K" gives -3 "6" gives 6 "149" gives 149 5 IARCLIB-1 Descriptions of C library functions atol long atol(const char *nptr) Parameters nptr A pointer to a string containing a number in ASCII form. Return value The long number found in the string. Description Converts the number found in the ASCII string pointed to by nptr to a long integer value, skipping white space and terminating upon reaching any unrecognized character. Header file stdlib.h Examples " -3K" gives -3 "6" gives 6 "149" gives 149 bsearch void *bsearch(const void *key, const void *base, size_t nmemb, size_t size, int (*compare) (const void *_key, const void *_base)); Parameters key Pointer to the searched for object. base Pointer to the array to search. nmemb Dimension of the array pointed to by base. size Size of the array elements. compare The comparison function which takes two arguments and returns: <0 (negative value) if _key is less than _base 0 if _key equals _base >0 (positive value) if _key is greater than _base IAR C Library Functions 6 Reference Guide IARCLIB-1 C library functions reference Return value Result Value Successful A pointer to the element of the array that matches the key. Unsuccessful Null. Table 1: bsearch return value Description Searches an array of nmemb objects, pointed to by base, for an element that matches the object pointed to by key. Header file stdlib.h calloc void *calloc(size_t nelem, size_t elsize) Parameters nelem The number of objects. elsize A value of type size_t specifying the size of each object. Return value Result Value Successful A pointer to the start (lowest address) of the memory block. Unsuccessful Zero if there is no memory block of the required size or greater available. Table 2: calloc return values Description Allocates a memory block for an array of objects of the given size. To ensure portability, the size is not given in absolute units of memory such as bytes, but in terms of a size or sizes returned by the sizeof function. The availability of memory depends on the default heap size, see the IAR C Compiler Reference Guide. Header file stdlib.h 7 IARCLIB-1 Descriptions of C library functions ceil double ceil(double arg) Parameters arg A double value. Return value A double having the smallest integral value greater than or equal to arg. Description Computes the smallest integral value greater than or equal to arg. Header file math.h cos double cos(double arg) Parameters arg A double value in radians. Return value The double cosine of arg. Description Computes the cosine of arg radians. Header file math.h cosh double cosh(double arg) Parameters arg A double value in radians. Return value The double hyperbolic cosine of arg. IAR C Library Functions 8 Reference Guide IARCLIB-1