6 LIBRARIES

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

6.1 Introduction

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.

6.2 Header Files

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.

6.3 C Libraries

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.

6.3.1 C Library Implementation Details

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

6.3.2 C Library Interface Description

_ioread

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.

_iowrite

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.

_simi

CrossView Pro I/O Simulation input interface function.

See also _ioread().

_simo

CrossView Pro I/O Simulation output interface function.

See also _iowrite().

_tolower

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.

_toupper

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.

abs

Returns the absolute value of the signed int argument.

acos

Returns the arccosine cos-1(x) of x in the range [0, pi],
x c [-1, 1].

asin

Returns the arcsine sin-1(x) of x in the range [-pi/2, pi/2],
x c [-1, 1].

assert

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:

is printed.

Returns nothing.

atan

Returns the arctangent tan-1(x) of x in the range [-pi/2, pi/2].
x
c [-1, 1].

atan2

Returns the result of: tan-1(y/x) in the range [-pi, pi].

atof

Converts the given string to a double value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the double value.

atoi

Converts the given string to an integer value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the integer value.

atol

Converts the given string to a long value. White space is skipped, conversion is terminated at the first unrecognized character.

Returns the long value.

bsearch

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.

calloc

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.

ceil

Returns the smallest integer not less than x, as a double.

clock

Determines the processor time used.

Returns number of microseconds since the last reset, assuming a 12 MHz cpu.

cos

Returns the cosine of x.

cosh

Returns the hyperbolic cosine of x.

div

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.

exit

Terminates the program normally. Acts as if 'main()' returns with status as the return value.

Returns zero, on successful termination.

exp

Returns the result of the exponential function ex.

fabs

Returns the absolute double value of x. |x|

fgetc

Reads one character from the given stream.

Returns the read character, or EOF on error.

fgets

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.

floor

Returns the largest integer not greater than x, as a double.

fmod

Returns the floating-point remainder of x/y, with the same sign as x. If y is zero, the result is implementation-defined.

fprintf

Performs a formatted write to the given stream.

See also printf(), _iowrite() and section 6.3.3, Printf and Scanf Formatting Routines.

fputc

Puts one character onto the given stream.

See also _iowrite().

Returns EOF on error.

fputs

Writes the string to a stream. The terminating NULL character is not written.

See also _iowrite().

Returns NULL if successful, or EOF on error.

fread

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.

free

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

frexp

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.

fscanf

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.

fwrite

Writes nobj members of size bytes to the given stream from the array pointed to by ptr.

Returns the number of successfully written objects.

getc

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.

getchar

Reads one character from standard input.

See also _ioread().

Returns the character read or EOF on error.

gets

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.

ididcpy

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

ididmove

Moves n bytes of data from idat memory to idat memory. Overlapping spaces are handled correctly.

See also ididcpy().

idxdcpy

Copies n bytes of data from idat memory to xdat memory.

See also ididcpy().

idxdmove

Moves n bytes of data from idat memory to xdat memory.

See also ididcpy().

isalnum

Returns a non-zero value when c is an alphabetic character or a number ([A-Z][a-z][0-9]).

isalpha

Returns a non-zero value when c is an alphabetic character ([A-Z][a-z]).

isascii

Returns a non-zero value when c is in the range of 0 and 127. This is a non-ANSI function.

iscntrl

Returns a non-zero value when c is a control character.

isdigit

Returns a non-zero value when c is a numeric character ([0-9]).

isgraph

Returns a non-zero value when c is printable, but not a space.

islower

Returns a non-zero value when c is a lowercase character ([a-z]).

isprint

Returns a non-zero value when c is printable, including spaces.

ispunct

Returns a non-zero value when c is a punctuation character (such as '.', ',', '!', etc.).

isspace

Returns a non-zero value when c is a space type character (space, tab, vertical tab, formfeed, linefeed, carriage return).

isupper

Returns a non-zero value when c is an uppercase character ([A-Z]).

isxdigit

Returns a non-zero value when c is a hexadecimal digit ([0-9][A-F][a-f]).

labs

Returns the absolute value of the signed long argument.

ldexp

Returns the result of: 2 n.

ldiv

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.

log

Returns the natural logarithm ln(x), x>0.

log10

Returns the base 10 logarithm log10(x), x>0.

longjmp

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.

malloc

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.

memchr

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.

memcmp

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.

memcpy

Copies n characters from ct to s. No care is taken if the two objects overlap.

Returns s

memmove

Copies n characters from ct to s. Overlapping objects will be handled correctly.

Returns s

memset

Fills the first n bytes of s with character c.

Returns s

modf

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.

offsetof

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.

pow

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.

printf

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

putc

Puts one character onto the given stream.

See also _iowrite().

Returns EOF on error.

putchar

Puts one character onto standard output.

See also _iowrite().

Returns the character written or EOF on error.

puts

Writes the string to stdout, the string is terminated by a newline.

See also _iowrite().

Returns NULL if successful, or EOF on error.

qsort

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.

rand

Returns a sequence of pseudo-random integers, in the range 0 to RAND_MAX.

realloc

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.

romidcpy

Copies n bytes of data from ROM memory to idat memory.

See also ididcpy().

romidmove

Moves n bytes of data from ROM memory to idat memory.

See also ididcpy().

romxdcpy

Copies n bytes of data from ROM memory to xdat memory.

See also ididcpy().

romxdmove

Moves n bytes of data from ROM memory to xdat memory.

See also ididcpy().

scanf

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.

setjmp

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().

sin

Returns the sine of x.

sinh

Returns the hyperbolic sine of x.

sprintf

Performs a formatted write to a string.

See also printf() and section 6.3.3, Printf and Scanf Formatting Routines.

sqrt

Returns the square root of x. Vx, where x >= 0.

srand

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.

sscanf

Performs a formatted read from a string.

See also scanf() and section 6.3.3, Printf and Scanf Formatting Routines.

strcat

Concatenates string ct to string s, including the trailing NULL character.

Returns s

strchr

Returns a pointer to the first occurrence of character c in the string cs. If not found, NULL is returned.

strcmp

Compares string cs to string ct.

Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.

strcpy

Copies string ct into the string s, including the trailing NULL character.

Returns s

strcspn

Returns the length of the prefix in string cs, consisting of characters not in the string ct.

strlen

Returns the length of the string in cs, not counting the NULL character.

strncat

Concatenates string ct to string s, at most n characters are copied. Add a trailing NULL character.

Returns s

strncmp

Compares at most n bytes of string cs to string ct.

Returns <0 if cs < ct,
0 if cs == ct,
>0 if cs > ct.

strncpy

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

strpbrk

Returns a pointer to the first occurrence in cs of any character out of string ct. If none are found, NULL is returned.

strrchr

Returns a pointer to the last occurrence of c in the string cs. If not found, NULL is returned.

strspn

Returns the length of the prefix in string cs, consisting of characters in the string ct.

strstr

Returns a pointer to the first occurrence of string ct in the string cs. Returns NULL if not found.

strtod

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.

strtok

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.

strtol

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.

strtoul

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.

tan

Returns the tangent of x.

tanh

Returns the hyperbolic tangent of x.

time

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.

toascii

Converts c to an ascii value (strip highest bit). This is a non-ANSI function.

Returns the converted value.

tolower

Returns c converted to a lowercase character if it is an uppercase character, otherwise c is returned.

toupper

Returns c converted to an uppercase character if it is a lowercase character, otherwise c is returned.

ungetc

Pushes at the most one character back onto the input buffer.

Returns EOF on error.

va_arg

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.

va_end

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

va_start

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.

vfprintf

Is equivalent to vprintf, but writes to the given stream.

See also vprintf(), _iowrite() and section 6.3.3, Printf and Scanf Formatting Routines.

vprintf

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.

vsprintf

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.

xdidcpy

Copies n bytes of data from xdat memory to idat memory.

See also ididcpy().

xdidmove

Moves n bytes of data from xdat memory to idat memory.

See also ididcpy().

xdxdcpy

Copies n bytes of data from xdat memory to xdat memory.

See also ididcpy().

xdxdmove

Moves n bytes of data from xdat memory to xdat memory. Overlapping spaces are handled correctly.

See also ididcpy().

6.3.3 Printf and Scanf Formatting Routines

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.

6.4 Run-time Library

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.

6.5 Creating your own 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.


Copyright © 2002 Altium BV