This chapter contains the following sections:
Introduction
Header Files
C Libraries
C Library Implementation Details
C Library Interface Description
Printf and Scanf Formatting Routines
Run-time Library
Creating your own C Library
This chapter describes the library functions delivered with the compiler. Some functions (e.g. printf(), scanf()) can be edited to match your needs. cc51 comes with libraries in object format per memory model and with header files containing the appropriate prototype of the library functions. The library functions are also shipped in source code (C or assembly).
A number of standard operations within C are too complex to generate inline code for (e.g. 16 bit signed divide). These operations are implemented as run-time library functions. The run-time library routines are added to the C library.
The following header files are delivered with the C compiler:
<assert.h> assert
<cc51.h> Special file with cc51 definitions. No C functions.
<ctype.h> isalnum, isalpha, isascii, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, toascii, _tolower, tolower, _toupper, toupper
<errno.h> Error numbers. No C functions.
<float.h> Constants related to floating point arithmetic.
<keil.h> Support for migration from Keil C-51 to TASKING C-51.
<limits.h> Limits and sizes of integral types. No C functions.
<math.h> acos, asin, atan, atan2, ceil, cos, cosh, exp, fabs, floor, fmod, frexp, ldexp, log, log10, modf, pow, sin, sinh, sqrt, tan, tanh
<setjmp.h> longjmp, setjmp
<simio.h> _simi, _simo
<stdarg.h> va_arg, va_end, va_start
<stddef.h> offsetof, definition of special types.
<stdio.h> fgetc, fgets, fprintf, fputc, fputs, fread, fscanf, fwrite, getc, getchar, gets, _ioread, _iowrite, printf, putc, putchar, puts, scanf, sprintf, sscanf, ungetc, vfprintf, vprintf, vsprintf
<stdlib.h> abs, atof, atoi, atol, bsearch, calloc, div, exit, free, labs, ldiv, malloc, qsort, rand, realloc, strtod, strtol, strtoul, srand
<string.h> memchr, memcmp, memcpy, memmove, memset, strcat, strchr, strcmp, strcpy, strcspn, strlen, strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtok, ididcpy, ididmove, idxdcpy, idxdmove, romidcpy, romidmove, romxdcpy, romxdmove, xdidcpy, xdidmove, xdxdcpy, xdxdmove
<time.h> clock, time. All functions are delivered as skeletons.
The C library contains C library functions. All C library functions are described in this chapter. These functions are only called by explicit function calls in your application program.
The C library uses the following name syntax:
Compiler Model | Library to link | ||
Non-protected | Protected | ||
Small (default) | (-Ms) | c51s.lib | c51sp.lib |
Small for 751 derivative | (-Ms -rs) | c751s.lib | c751sp.lib |
Auxpage | (-Ma) | c51a.lib | c51ap.lib |
Large | (-Ml) | c51l.lib | c51lp.lib |
Reentrant | (-Mr) | c51r.lib | c51rp.lib |
Table 6-1: C library name syntax
The c751s.lib library is made especially for the 80751/80752 derivatives, (containing a small amount of ROM, no extern RAM is possible). All routines which use pdat or xdat variables are removed from this library.
Use the protected libraries to prevent the occurrence of interrupts while updating the virtual stack pointer.
In EDE you can select a protected library by enabling
the option Use protection on virtual stack pointer updates in the Linker | Stack/Heap entry of the Project | Project Options... dialog.
Description | Library to link | |
For all models: | ||
Floating Point Library (needs external RAM) | float.lib | |
Floating Point Library (basic fp operations, no external RAM neeeded) | floats.lib |
Table 6-2: Floating point library name syntax
See section 6.3.3
, Printf and Scanf Formatting Routines, for the name syntax of the delivered printf and scanf libraries.
See section 7.8
, Multiple Data Pointer Support in chapter Run-time Environment, for
the name syntax of the multiple data pointer libraries.
When you use a derivative without external RAM (like the 80751/80752) you cannot use the default floating point library float.lib, since that library uses external RAM. In that case use the floating point library floats.lib instead.
When you use floating point, the library float.lib must always be the last library linked, it should be placed after the, C library. For further explanation how to link your application, see section 7.11 Linking an Application in chapter Run Time Environment.
The floating point library floats.lib does not need any external RAM. When you use this library you have to change the startup code to place the floating point stack in internal RAM. Arithmetic routines link sin(), cos(), etc. are not present in this library, only basic floating point operations can be done.
Using the reentrant model, you might need to change some routines. See section 7.10, Reentrant Model / _reentrant Functions in chapter Run-time Environment.
In order to allow the library functions to use a NULL pointer as an illegal address, you should avoid memory location xdat:0 to be referred to by a pointer. You can achieve this by either using the linker RESERVE control (e.g. reserve 1 byte: RESERVE(xdata(0,0))), or be sure that this memory location is occupied by a plain (static) variable (which is not pointed to by a pointer).
In EDE you can prevent pointers on address 0 by enabling the option Reserve first byte of XDATA to prevent pointers on address0 in the Linker | Reserved Areas entry of the Project | Project Options... dialog.
A detailed description of the delivered C library is shown in the following list.
Explanation :
Y - Fully implemented
I - Implemented, but need some user written low level routine
L - Delivered as a skeleton
File |
Imple- mented | Routine name | Description / Reason |
assert.h | Y | 'assert()' macro | Macro definition |
ctype.h |
Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y |
isalnum isalpha iscntrl isdigit isgraph islower isprint ispunct isspace isupper isxdigit tolower toupper _tolower _toupper isascii toascii |
Most of the routines are delivered as macro AND as function (as prescribed by ANSI). Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI |
errno.h | Y | Only Macros | |
float.h | Y | ||
limits.h | Y | Only Macros | |
math.h |
Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y |
acos asin atan atan2 ceil cos cosh exp fabs floor fmod frexp ldexp log log10 modf pow sin sinh sqrt tan tanh | |
setjmp.h |
Y Y Y |
longjmp setjmp | |
stdarg.h |
Y Y Y Y |
va_arg va_end va_start | |
stddef.h | Y | Only Macros | |
stdio.h |
Y I I I I I I I I |
fgetc fgets fprintf fputc fputs fread fscanf fwrite |
Due to 'stdarg.h/varargs.h' conflicts, the routines 'vprintf()', 'vfprintf()', 'vsprintf()' are not ANSI yet. Needs _ioread Needs _ioread Needs _iowrite Needs _iowrite Needs _iowrite Needs _ioread Needs _ioread Needs _iowrite |
I I I I I I I I Y Y Y I I Y I I |
getc getchar gets printf putc putchar puts scanf sprintf sscanf ungetc vfprintf vprintf vsprintf _ioread _iowrite |
Needs _ioread Needs _ioread Needs _ioread Needs _iowrite Needs _iowrite Needs _iowrite Needs _iowrite Needs _ioread Needs _iowrite Needs _iowrite Low level input routine Low level output routine | |
stdlib.h |
Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y |
abs atof atoi atol bsearch calloc div exit free labs ldiv malloc qsort rand realloc strtod strtol strtoul srand |
Calls __EXIT in cstart |
string.h |
Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y |
memchr memcmp memcpy memmove memset strcat strchr strcmp strcpy strcspn strlen strncat strncmp strncpy strpbrk strrchr strspn strstr strtok ididcpy ididmove idxdcpy idxdmove romidcpy romidmove romxdcpy romxdmove xdidcpy xdidmove xdxdcpy xdxdmove |
Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI Not defined by ANSI |
time.h |
Y I I |
clock time |
real time clock not supported Uses SFRs 0xC1 to 0xC4 |
#include <stdio.h> _regparm int _ioread( FILE *fp );
Low level input function. The delivered library contains a call to "_simi()". To perform real I/O, you must customize this function. _ioread is used by all input functions (scanf, getc, gets, etc.). See the file _ioread.c in the lib\src directory demonstrating an example implementation of this low level input function using the CrossView Pro I/O Simulation input feature.
#include <stdio.h> _regparm int _iowrite( int c, FILE *fp );
Low level output function. The delivered library contains a call to "_simo()". To perform real I/O, you must customize this function. _iowrite is used by all output functions (printf, putc, puts, etc.). See the file _iowrite.c in the lib\src directory demonstrating an example implementation of this low level output function using the CrossView Pro I/O Simulation output feature.
#include <simio.h> void _regparm _simi( unsigned char stream, char *port, unsigned char len );
CrossView Pro I/O Simulation input interface function.
See also
_ioread().
#include <simio.h> void _regparm _simo( unsigned char stream, char *port, unsigned char len );
CrossView Pro I/O Simulation output interface function.
See also
_iowrite().
#include <ctype.h> _regparm int _tolower( int c );
Converts c to a lowercase character, does not check if c really is an uppercase character. This is a non-ANSI function.
Returns the converted character.
#include <ctype.h> _regparm int _toupper( int c );
Converts c to an uppercase character, does not check if c really is a lowercase character. This is a non-ANSI function.
Returns the converted character.
#include <stdlib.h> _regparm int abs( int n );
Returns the absolute value of the signed int argument.
#include <math.h> _regparm double acos( double x );
Returns the arccosine cos-1(x) of x in the range [0, pi],
x c [-1, 1].
#include <math.h> _regparm double asin( double x );
Returns the arcsine sin-1(x) of x in the range [-pi/2, pi/2],
x c [-1, 1].
#include <assert.h> _regparm void assert( int expr );
When compiled with NDEBUG, this is an empty macro. When compiled without NDEBUG defined, it checks if expr is true. If it is true, then a line like:
"Assertion failed: expression, file filename, line num"
is printed.
Returns nothing.
#include <math.h> _regparm double atan( double x );
Returns the arctangent tan-1(x) of x in the range [-pi/2, pi/2].
x c [-1, 1].
#include <math.h> _regparm double atan2( double y, double x );
Returns the result of: tan-1(y/x) in the range [-pi, pi].
#include <stdlib.h> _regparm double atof( const char *s );
Converts the given string to a double value. White space is skipped, conversion is terminated at the first unrecognized character.
Returns the double value.
#include <stdlib.h> _regparm int atoi( const char *s );
Converts the given string to an integer value. White space is skipped, conversion is terminated at the first unrecognized character.
Returns the integer value.
#include <stdlib.h> _regparm long atol( const char *s );
Converts the given string to a long value. White space is skipped, conversion is terminated at the first unrecognized character.
Returns the long value.
#include <stdlib.h> _regparm _reentrant void *bsearch( const void *key, const void *base, size_t n, size_t size, _regparm _reentrant int (* cmp) (const void *, const void *) );
This function searches in an array of n members, for the object pointed to by ptr. The initial base of the array is given by base. The size of each member is specified by size. The given array must be sorted in ascending order, according to the results of the function pointed to by cmp.
Returns a pointer to the matching member in the array, or NULL when not found.
#include <stdlib.h> _regparm void xdat *calloc( size_t nobj, size_t size );
The allocated space is filled with zeros. The maximum space that can be allocated can be changed by customizing the heap size (see section 7.5, Heap ). By default no heap is allocated. When "calloc()" is used while no heap is defined, the linker gives an error.
Be aware, for 'small' and 'aux' model, pointers to the allocated area must be declared as pointing to xdat.
Returns a pointer to space in external memory
for nobj items of size bytes length.
NULL if there is not enough space left.
#include <math.h> _regparm double ceil( double x );
Returns the smallest integer not less than x, as a double.
#include <time.h> clock_t clock( void );
Determines the processor time used.
Returns number of microseconds since the last reset, assuming a 12 MHz cpu.
#include <math.h> _regparm double cos( double x );
Returns the cosine of x.
#include <math.h> _regparm double cosh( double x );
Returns the hyperbolic cosine of x.
#include <stdlib.h> _regparm div_t div( int num, int denom );
Both arguments are integers. The returned quotient and remainder are also integers.
Returns a structure containing the quotient and remainder of num divided by denom.
#include <stdlib.h> _regparm void exit( int status );
Terminates the program normally. Acts as if 'main()' returns with status as the return value.
Returns zero, on successful termination.
#include <math.h> _regparm double exp( double x );
Returns the result of the exponential function ex.
#include <math.h> _regparm double fabs( double x );
Returns the absolute double value of x. |x|
#include <stdio.h> _regparm int fgetc( FILE *stream );
Reads one character from the given stream.
Returns the read character, or EOF on error.
#include <stdio.h> _regparm char *fgets( char *s, int n, FILE *stream );
Reads at most the next n-1 characters from the given stream into the array s until a newline is found.
Returns s, or NULL on EOF or error.
#include <math.h> _regparm double floor( double x );
Returns the largest integer not greater than x, as a double.
#include <math.h> _regparm double fmod( double x, double y );
Returns the floating-point remainder of x/y, with the same sign as x. If y is zero, the result is implementation-defined.
#include <stdio.h> _regparm int fprintf( FILE *stream, const char *format, ... );
Performs a formatted write to the given stream.
See also
printf(),
_iowrite() and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <stdio.h> _regparm int fputc( int c, FILE *stream );
Puts one character onto the given stream.
See also
_iowrite().
Returns EOF on error.
#include <stdio.h> _regparm int fputs( const char *s, FILE *stream );
Writes the string to a stream. The terminating NULL character is not written.
See also
_iowrite().
Returns NULL if successful, or EOF on error.
#include <stdio.h> _regparm size_t fread( void *ptr, size_t size, size_t nobj, FILE *stream );
Reads nobj members of size bytes from the given steam into the array pointed to by ptr.
See also
_ioread().
Returns the number of successfully read objects.
#include <stdlib.h> _regparm void free( void xdat *p );
Deallocates the space pointed to by p. p Must point to space earlier allocated by a call to "calloc()", "malloc()" or "realloc()". Otherwise the behavior is undefined.
See also
calloc(),
malloc() and
realloc().
Returns nothing
#include <math.h> _regparm double frexp( double x, int *exp );
Splits x into a normalized fraction in the interval [1/2, 1>, which is returned, and a power of 2, which is stored in *exp. If x is zero, both parts of the result are zero. For example: frexp( 4.0, &var ) results in 0.5·23. The function returns 0.5, and 3 is stored in var.
Returns the normalized fraction.
#include <stdio.h> _regparm int fscanf( FILE *stream, const char *format, ... );
Performs a formatted read from the given stream.
See also
scanf(),
_ioread() and section 6.3.3,
Printf and Scanf Formatting Routines.
Returns the number of items converted successfully.
#include <stdio.h> _regparm size_t fwrite( const void *ptr, size_t size, size_t nobj, FILE *stream );
Writes nobj members of size bytes to the given stream from the array pointed to by ptr.
Returns the number of successfully written objects.
#include <stdio.h> _regparm int getc( FILE *stream );
Reads one character out of the given stream. Currently #defined as getchar(), because FILE I/O is not supported.
See also
_ioread().
Returns the character read or EOF on error.
#include <stdio.h> _regparm int getchar( void );
Reads one character from standard input.
See also
_ioread().
Returns the character read or EOF on error.
#include <stdio.h> _regparm char *gets( char *s );
Reads all characters from standard input until a newline is found. The newline is replaced by a NULL-character.
See also
_ioread().
Returns a pointer to the read string or NULL on error.
#include <string.h> _regparm void idat * ididcpy( idat void *cs, idat void *ct, size_t n );
Copies n bytes of data from idat memory to idat memory without worrying if data spaces overlap.
Returns a pointer to ct.
The compiler is able to handle different types of memory, i.e. idat, data, pdat, xdat, const. Sometimes it is necessary to have the possibility to copy data from one memory to another. Therefore the next functions have been created and placed in the C library :
The functions xxxxcpy() copy data from one memory to another memory without worrying if data spaces overlap. The functions xxxxmove() first check if the data spaces overlap and then copy in the correct direction. When it is desired to copy to/from data, use the functions for idat (use a cast with the arguments). Moving data to pdat can be done by using the functions for xdat (use a cast with the arguments).
#include <string.h> _regparm void idat *ididmove( idat void *cs, idat void *ct, size_t n );
Moves n bytes of data from idat memory to idat memory. Overlapping spaces are handled correctly.
See also
ididcpy().
#include <string.h> _regparm void xdat *idxdcpy( xdat void *cs, const idat void *ct, size_t n );
Copies n bytes of data from idat memory to xdat memory.
See also
ididcpy().
#include <string.h> _regparm void xdat *idxdmove( xdat void *cs, const idat void *ct, size_t n );
Moves n bytes of data from idat memory to xdat memory.
See also
ididcpy().
#include <ctype.h> _regparm int isalnum( int c );
Returns a non-zero value when c is an alphabetic character or a number ([A-Z][a-z][0-9]).
#include <ctype.h> _regparm int isalpha( int c );
Returns a non-zero value when c is an alphabetic character ([A-Z][a-z]).
#include <ctype.h> _regparm int isascii( int c );
Returns a non-zero value when c is in the range of 0 and 127. This is a non-ANSI function.
#include <ctype.h> _regparm int iscntrl( int c );
Returns a non-zero value when c is a control character.
#include <ctype.h> _regparm int isdigit( int c );
Returns a non-zero value when c is a numeric character ([0-9]).
#include <ctype.h> _regparm int isgraph( int c );
Returns a non-zero value when c is printable, but not a space.
#include <ctype.h> _regparm int islower( int c );
Returns a non-zero value when c is a lowercase character ([a-z]).
#include <ctype.h> _regparm int isprint( int c );
Returns a non-zero value when c is printable, including spaces.
#include <ctype.h> _regparm int ispunct( int c );
Returns a non-zero value when c is a punctuation character (such as '.', ',', '!', etc.).
#include <ctype.h> _regparm int isspace( int c );
Returns a non-zero value when c is a space type character (space, tab, vertical tab, formfeed, linefeed, carriage return).
#include <ctype.h> _regparm int isupper( int c );
Returns a non-zero value when c is an uppercase character ([A-Z]).
#include <ctype.h> _regparm int isxdigit( int c );
Returns a non-zero value when c is a hexadecimal digit ([0-9][A-F][a-f]).
#include <stdlib.h> _regparm long labs( long n );
Returns the absolute value of the signed long argument.
#include <math.h> _regparm double ldexp( double x, int n );
Returns the result of: x·2 n.
#include <stdlib.h> _regparm ldiv_t ldiv( long num, long denom );
Both arguments are long integers. The returned quotient and remainder are also long integers.
Returns a structure containing the quotient and remainder of num divided by denom.
#include <math.h> _regparm double log( double x );
Returns the natural logarithm ln(x), x>0.
#include <math.h> _regparm double log10( double x );
Returns the base 10 logarithm log10(x), x>0.
#include <setjmp.h> _regparm void longjmp( jmp_buf env, int val );
Restores the environment previously saved with a call to setjmp(). The function calling the corresponding call to setjmp() may not be terminated yet. The value of val should not be zero.
Returns nothing.
#include <stdlib.h> _regparm void xdat *malloc( size_t size );
The allocated space is not initialized. The maximum space that can be allocated can be changed by customizing the heap size (see section 7.5, Heap ). By default no heap is allocated. When "malloc()" is used while no heap is defined, the linker gives an error.
Be aware, for 'small' and 'aux' model, pointers to the allocated area must be declared as pointing to xdat.
Returns a pointer to space in external memory of size bytes length. NULL if there is not enough space left.
#include <string.h> _regparm void *memchr( const void *cs, int c, size_t n );
Checks the first n bytes of cs on the occurrence of character c.
Returns NULL when not found, otherwise a pointer to the found character is returned.
#include <string.h> _regparm int memcmp( const void *cs, const void *ct, size_t n );
Compares the first n bytes of cs with the contents of ct.
Returns a value < 0 if cs < ct,
0 if cs = = ct,
or a value > 0 if cs > ct.
#include <string.h> _regparm void *memcpy( void *s, const void *ct, size_t n );
Copies n characters from ct to s. No care is taken if the two objects overlap.
Returns s
#include <string.h> _regparm void *memmove( void *s, const void *ct, size_t n );
Copies n characters from ct to s. Overlapping objects will be handled correctly.
Returns s
#include <string.h> _regparm void *memset( void *s, int c, size_t n );
Fills the first n bytes of s with character c.
Returns s
#include <math.h> _regparm double modf( double x, double *ip );
Splits x into integral and fractional parts, each with the same sign as x. It stores the integral part in *ip.
Returns the fractional part.
#include <stddef.h> _regparm int offsetof( type, member );
Returns the offset for the given member in an object of type.
Be aware, offsetof() for bitstructures/unions may give unpredictable results. Also the offsetof() of a bit field is undefined.
#include <math.h> _regparm double pow( double x, double y );
A domain error occurs if x=0 and y<=0, or if x<0 and y is not an integer.
Returns the result of x raised to the power of y: xy.
#include <stdio.h> _regparm int printf( const char *format, ... );
Performs a formatted write to the standard output stream.
See also
_iowrite() and section 6.3.3, Printf and Scanf Formatting Routines.
Returns the number of characters written to the output stream.
The format string may contain plain text mixed with conversion specifiers. Each conversion specifier should be preceded by a '%' character. The conversion specifier should be build in order:
- Flags (in any order):
- specifies left adjustment of the converted argument.
+ a number
is always preceded with a sign character.
+ has higher
precedence as space.
space a negative number is preceded with a sign, positive numbers with a space.
0 specifies padding to the field width with zeros (only for numbers).
# specifies an alternate output form. For o, the first digit will be zero. For x or X, "0x" and "0X" will be prefixed to the number. For e, E, f, g, G, the output always contains a decimal point, trailing zeros are not removed.
- A number specifying a minimum field width. The converted argument is printed in a field with at least the length specified here. If the converted argument has fewer characters than specified, it will be padded at the left side (or at the right when the flag '-' was specified) with spaces. Padding to numeric fields will be done with zeros when the flag '0' is also specified (only when padding left). Instead of a numeric value, also '*' may be specified, the value is then taken from the next argument, which is assumed to be of type int.
- A period. This separates the minimum field width from the precision.
- A number specifying the maximum length of a string to be printed. Or the number of digits printed after the decimal point (only for floating point conversions). Or the minimum number of digits to be printed for an integer conversion. Instead of a numeric value, also '*' may be specified, the value is then taken from the next argument, which is assumed to be of type int.
- A length modifier 'h', 'l' or 'L'. 'h' indicates that the argument is to be treated as a short or unsigned short number. 'l' should be used if the argument is a long integer. 'L' indicates that the argument is a long double.
Flags, length specifier, period, precision and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined:
Character | Printed as |
d, i | int, signed decimal |
o | int, unsigned octal |
x, X | int, unsigned hexadecimal in lowercase or uppercase respectively |
u | int, unsigned decimal |
c | int, single character (converted to unsigned char) |
s | char *, the characters from the string are printed until a NULL character is found. When the given precision is met before, printing will also stop |
f | double |
e, E | double |
g, G | double |
n | int *, the number of characters written so far is written into the argument. This should be a pointer to an integer in default memory. No value is printed. |
% | No argument is converted, a '%' is printed. |
Table 6-3: Printf conversion characters
The 'p' conversion character is not supported because the formatter is unable to know to which memory the pointer is pointing to. However, you can print pointers as unsigned decimal ('u' conversion character).
#include <stdio.h> _regparm int putc( int c, FILE *stream );
Puts one character onto the given stream.
See also
_iowrite().
Returns EOF on error.
#include <stdio.h> _regparm int putchar( int c );
Puts one character onto standard output.
See also
_iowrite().
Returns the character written or EOF on error.
#include <stdio.h> _regparm int puts( const char *s );
Writes the string to stdout, the string is terminated by a newline.
See also
_iowrite().
Returns NULL if successful, or EOF on error.
#include <stdlib.h> _regparm _reentrant void qsort( void *base, size_t n, size_t size, _regparm _reentrant int (* cmp)(const void *, const void *) );
This function sorts an array of n members. The initial base of the array is given by base. The size of each member is specified by size. The given array is sorted in ascending order, according to the results of the function pointed to by cmp.
#include <stdlib.h> _regparm int rand( void );
Returns a sequence of pseudo-random integers, in the range 0 to RAND_MAX.
#include <stdlib.h> _regparm void xdat *realloc( void *p, size_t size );
Reallocates the space for the object pointed to by p. The contents of the object will be the same as before calling realloc().The maximum space that can be allocated can be changed by customizing the heap size (see section 7.5, Heap ). By default no heap is allocated. When "realloc()" is used while no heap is defined, the linker gives an error.
See also
malloc().
Returns NULL and *p is not changed, if there is not enough space for the new allocation. Otherwise a pointer to the newly allocated space for the object is returned.
#include <string.h> _regparm void idat *romidcpy( idat void *cs, const rom void *ct, size_t n );
Copies n bytes of data from ROM memory to idat memory.
See also
ididcpy().
#include <string.h> _regparm void idat *romidmove( idat void *cs, const rom void *ct, size_t n );
Moves n bytes of data from ROM memory to idat memory.
See also
ididcpy().
#include <string.h> _regparm void xdat *romxdcpy( xdat void *cs, const rom void *ct, size_t n );
Copies n bytes of data from ROM memory to xdat memory.
See also
ididcpy().
#include <string.h> _regparm void xdat *romxdmove( xdat void *cs, const rom void *ct, size_t n );
Moves n bytes of data from ROM memory to xdat memory.
See also
ididcpy().
#include <stdio.h> _regparm int scanf( const char *format, ... );
Performs a formatted read from the standard input stream.
See also
_ioread() and section 6.3.3, Printf and Scanf Formatting Routines.
Returns the number of items converted successfully.
All arguments to this function should be pointers to variables (in default memory) of the type which is specified in the format string.
The format string may contain :
- Blanks or tabs, which are skipped.
- Normal characters (not '%'), which should be matched exactly in the input stream.
- Conversion specifications, starting with a '%' character.
Conversion specifications should be build as follows (in order) :
- A '*', meaning that no assignment is done for this field.
- A number specifying the maximum field width.
- A length modifier 'h', 'l' or 'L'. 'h' indicates the argument is to be treated as a short or unsigned short number. 'l' should be used if the argument is a long integer. 'L' indicates that the argument is a long double.
- A conversion specifier. '*', maximum field width and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined.
Length specifier and length modifier are optional, the conversion character is not. The conversion character must be one of the following, if a character following '%' is not in the list, the behavior is undefined.
Character | Scanned as |
d | int, signed decimal. |
i | int, the integer may be given octal (i.e. a leading 0 is entered) or hexadecimal (leading "0x" or "0X"), or just decimal. |
o | int, unsigned octal. |
u | int, unsigned decimal. |
x | int, unsigned hexadecimal in lowercase or uppercase. |
c | single character (converted to unsigned char). |
s | char *, a string of non white space characters. The argument should point to an array of characters, large enough to hold the string and a terminating NULL character. |
f | float |
e, E | float |
g, G | float |
n | int *, the number of characters written so far is written into the argument. No scanning is done. |
[...] | Matches a string of input characters from the set between the brackets. A NULL character is added to terminate the string. Specifying []...] includes the ']' character in the set of scanning characters. |
[^...] | Matches a string of input characters not in the set between the brackets. A NULL character is added to terminate the string. Specifying [^]...] includes the ']' character in the set. |
% | Literal '%', no assignment is done. |
Table 6-4: Scanf conversion characters
The 'p' specifier is not supported because the formatter is unable to know to which memory the pointer is pointing to.
#include <setjmp.h> _regparm int setjmp( jmp_buf env );
Saves the current environment for a subsequent call to longjmp.
Returns the value 0 after a direct call to setjmp(). Calling the function "longjmp()" using the saved env will restore the current environment and jump to this place with a non-zero return value.
See also
longjmp().
#include <math.h> _regparm double sin( double x );
Returns the sine of x.
#include <math.h> _regparm double sinh( double x );
Returns the hyperbolic sine of x.
#include <stdio.h> _regparm int sprintf( char *s, const char *format, ... );
Performs a formatted write to a string.
See also
printf() and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <math.h> _regparm double sqrt( double x );
Returns the square root of x. Vx, where x >= 0.
#include <stdlib.h> _regparm void srand( unsigned int seed );
This function uses seed as the start of a new sequence of pseudo-random numbers to be returned by subsequent calls to srand(). When srand is called with the same seed value, the sequence of pseudo-random numbers generated by rand() will be repeated.
Returns pseudo random numbers.
#include <stdio.h> _regparm int sscanf( char *s, const char *format, ... );
Performs a formatted read from a string.
See also
scanf()
and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <string.h> _regparm char *strcat( char *s, const char *ct );
Concatenates string ct to string s, including the trailing NULL character.
Returns s
#include <string.h> _regparm char *strchr( const char *cs, int c );
Returns a pointer to the first occurrence of character c in the string cs. If not found, NULL is returned.
#include <string.h> _regparm int strcmp( const char *cs, const char *ct );
Compares string cs to string ct.
Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.
#include <string.h> _regparm char *strcpy( char *s, const char *ct );
Copies string ct into the string s, including the trailing NULL character.
Returns s
#include <string.h> _regparm size_t strcspn( const char *cs, const char *ct );
Returns the length of the prefix in string cs, consisting of characters not in the string ct.
#include <string.h> _regparm size_t strlen( const char *cs );
Returns the length of the string in cs, not counting the NULL character.
#include <string.h> _regparm char *strncat( char *s, const char *ct, size_t n );
Concatenates string ct to string s, at most n characters are copied. Add a trailing NULL character.
Returns s
#include <string.h> _regparm int strncmp( const char *cs, const char *ct, size_t n );
Compares at most n bytes of string cs to string ct.
Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.
#include <string.h> _regparm char *strncpy( char *s, const char *ct, size_t n );
Copies string ct onto the string s, at most n characters are copied. Add a trailing NULL character if the string is smaller than n characters.
Returns s
#include <string.h> _regparm char *strpbrk( const char *cs, const char *ct );
Returns a pointer to the first occurrence in cs of any character out of string ct. If none are found, NULL is returned.
#include <string.h> _regparm char *strrchr( const char *cs, int c );
Returns a pointer to the last occurrence of c in the string cs. If not found, NULL is returned.
#include <string.h> _regparm size_t strspn( const char *cs, const char *ct );
Returns the length of the prefix in string cs, consisting of characters in the string ct.
#include <string.h> _regparm char *strstr( const char *cs, const char *ct );
Returns a pointer to the first occurrence of string ct in the string cs. Returns NULL if not found.
#include <stdlib.h> _regparm double strtod( const char *s, char **endp );
Converts the initial portion of the string pointed to by s to a double value. Initial white spaces are skipped. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.
Returns the read value.
#include <string.h> _regparm char *strtok( char *s, const char *ct );
Search the string s for tokens delimited by characters from string ct. It terminates the token with a NULL character.
Returns a pointer to the token. A subsequent call
with
s == NULL will return the next token in the string.
#include <stdlib.h> _regparm long strtol( const char *s, char **endp, int base );
Converts the initial portion of the string pointed to by s to a long integer. Initial white spaces are skipped. Then a value is read using the given base. When base is zero, the base is taken as defined for integer constants. I.e. numbers starting with an '0' are taken octal, numbers starting with '0x' or '0X' are taken hexadecimal. Other numbers are taken decimal. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.
Returns the read value.
#include <stdlib.h> _regparm unsigned long strtoul( const char *s, char **endp, int base );
Converts the initial portion of the string pointed to by s to an unsigned long integer. Initial white spaces are skipped. Then a value is read using the given base. When base is zero, the base is taken as defined for integer constants. I.e. numbers starting with an '0' are taken octal, numbers starting with '0x' or '0X' are taken hexadecimal. Other numbers are taken decimal. When endp is not a NULL pointer, after this function is called, *endp will point to the first character not used by the conversion.
Returns the read value.
#include <math.h> _regparm double tan( double x);
Returns the tangent of x.
#include <math.h> _regparm double tanh( double x);
Returns the hyperbolic tangent of x.
#include <time.h> time_t time( time_t *tp );
The return value is also assigned to *tp, if tp is not NULL.
Returns the current calendar time, or -1 if the time is not available.
#include <ctype.h> _regparm int toascii( int c );
Converts c to an ascii value (strip highest bit). This is a non-ANSI function.
Returns the converted value.
#include <ctype.h> _regparm int tolower( int c );
Returns c converted to a lowercase character if it is an uppercase character, otherwise c is returned.
#include <ctype.h> _regparm int toupper( int c );
Returns c converted to an uppercase character if it is a lowercase character, otherwise c is returned.
#include <stdio.h> _regparm int ungetc( int c, FILE *fin );
Pushes at the most one character back onto the input buffer.
Returns EOF on error.
#include <stdarg.h> _regparm va_arg( va_list ap, type );
Returns the value of the next argument in the variable argument list. It's return type has the type of the given argument type. A next call to this macro will return the value of the next argument.
#include <stdarg.h> _regparm va_end( va_list ap );
This macro must be called after the arguments have been processed. It should be called before the function using the macro 'va_start' is terminated (ANSI specification).
#include <stdarg.h> _regparm va_start( va_list ap, lastarg );
This macro initializes ap. After this call, each call to va_arg() will return the value of the next argument. In our implementation, va_list cannot contain any bit type variables. Also the given argument lastarg must be the last non-bit type argument in the list.
#include <stdio.h> _regparm int vfprintf( FILE *stream, const char *format, va_list arg );
Is equivalent to vprintf, but writes to the given stream.
See also
vprintf(),
_iowrite() and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <stdio.h> _regparm int vprintf( const char *format, va_list arg );
Does a formatted write to standard output. Instead of a variable argument list as for printf(), this function expects a pointer to the list.
See also
printf(),
_iowrite() and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <stdio.h> _regparm int vsprintf( char *s, const char *format, va_list arg );
Does a formatted write a string. Instead of a variable argument list as for printf(), this function expects a pointer to the list.
See also
printf(),
_iowrite() and section 6.3.3,
Printf and Scanf Formatting Routines.
#include <string.h> _regparm void idat *xdidcpy( idat void *cs, const xdat void *ct, size_t n );
Copies n bytes of data from xdat memory to idat memory.
See also
ididcpy().
#include <string.h> _regparm void idat *xdidmove( idat void *cs, const xdat void *ct, size_t n );
Moves n bytes of data from xdat memory to idat memory.
See also
ididcpy().
#include <string.h> _regparm void xdat *xdxdcpy( xdat void *cs, xdat void *ct, size_t n );
Copies n bytes of data from xdat memory to xdat memory.
See also
ididcpy().
#include <string.h> _regparm void xdat *xdxdmove( xdat void *cs, xdat void *ct, size_t n );
Moves n bytes of data from xdat memory to xdat memory. Overlapping spaces are handled correctly.
See also
ididcpy().
The functions printf(), fprintf(), vfprintf(), vsprintf(), ... call one single function that deals with the format string and arguments. This function is _doprint(). This is a rather big function because the number of possibilities of the format specifiers in a format string are large. If you do not use all the possibilities of the format specifiers a smaller _doprint() function can be used. Three different versions exist:
The same applies to all scanf type functions, which all call the function _doscan(). Two different versions exist:
Special versions of the formatters are installed which can handle a format string placed in ROM.
The default printf formatter used in the C library is the MEDIUM version (printfsm.lib). The default scanf formatter used in the C library is the SMALL version (scanfss.lib). You can select different formatters by linking separate libraries with your application.
The printf/scanf libraries included with the product have the following name syntax:
where,
model indicates the compiler model s (small), a (auxpage), l (large) or r (reentrant)
pversion indicates the printf formatter version s (small), m (medium) or l (large)
sversion indicates the scanf formatter version s (small) or m (medium)
f (optionally) indicates that the format string is in ROM
When you use EDE, you can specify the printf/scanf libraries in the Compiler | Printf/Scanf entry of the Project | Project Options... dialog.
Section 3.4
, Function Parameters and section 3.10,
Strings.
Some compiler generated code contains calls to run-time library functions that would use too much code if generated as inline code. The name of a run-time library function always contains two leading underscores. For example, to perform a 16 bit unsigned division on two 'register-pairs', the function __UDIVI is called.
Because cc51 generates assembly code (and not object code) it prepends an underscore for the names of (public) C variables to distinguish these symbols from 8051 registers. So if you use a function with a leading underscore, the assembly label for this function contains two leading underscores. This function name could cause a name conflict (double defined) with one of the run-time library functions. However, ANSI states that it is not portable to use names starting with an underscore for public C variables and functions, because results are implementation defined.
All code of the run-time library functions is placed in a CODE segment called ?C51RTL_PR.
The run-time library functions are included in the C library.
There are several reasons why it is desired to have a specially adapted C library. Therefore all C sources of all library functions are delivered with the compiler (this file is placed in the directory cc51\lib\src when using PC, /usr/local/cc51/lib/src when using UNIX).
When creating your own library, the order of the objects in the library file is very important. To know the exact order in which the objects should be placed in the library, make a list of the order in which the delivered libraries are made by using the command 'ar51 t c51r.lib' (or c51l.lib or one of the other libraries).
The easiest method to create your own library is to make a copy of the existing library (use the library in the same memory model you want to create) and replace the existing objects in it by your own made objects with the command 'ar51 crv libname objectname ...' . This way the order of the objects in the library will be maintained. At link time you only have to link the newly made library to your application instead of a delivered library.
When starting with an empty library you have to link the original library also, because it contains all run-time routines needed to run your application. In this case the original library must be the last file specified to link51.