Library Reference - Library Reference

Next Next Topic

Library Reference

The C51 run-time library provides you with more than 100 predefined functions and macros to use in your 8051 C programs. This library makes embedded software development easier by providing you with routines that perform common programming tasks such as string and buffer manipulation, data conversion, and floating-point math operations.

Typically, the routines in this library conform to the ANSI C Standard. However, some functions differ slightly in order to take advantage of the features found in the 8051 architecture. For example, the function isdigit returns a bit value as opposed to an int. Where possible, function return types and argument types are adjusted to use the smallest possible data type. In addition, unsigned data types are favored over signed types. These alterations to the standard library provide a maximum of performance while also reducing program size.

All routines in this library are implemented to be independent of and to function using any register bank.


Intrinsic Routines

The C51 compiler supports a number of intrinsic library functions. Non-intrinsic functions generate ACALL or LCALL instructions to perform the library routine. Intrinsic functions generate in-line code to perform the library routine. The generated in-line code is much faster and more efficient than a called routine would be. The following functions are available in intrinsic form:

Routine | Attributes | Description
_chkfloat_ | intrinsic, reentrant | Checks the status of float numbers.
_crol_ | intrinsic, reentrant | Rotates an unsigned char left a specified number of bits.
_cror_ | intrinsic, reentrant | Rotates an unsigned char right a specified number of bits.
_irol_ | intrinsic, reentrant | Rotates an unsigned int left a specified number of bits.
_iror_ | intrinsic, reentrant | Rotates an unsigned int right a specified number of bits.
_lrol_ | intrinsic, reentrant | Rotates an unsigned long left a specified number of bits.
_lror_ | intrinsic, reentrant | Rotates an unsigned long right a specified number of bits.
_nop_ | intrinsic, reentrant | Inserts an 8051 NOP instruction.
_testbit_ | intrinsic, reentrant | Tests the value of a bit and clears it to 0.

These routines are described in detail in the following sections.


Library Files

The C51 library includes six different compile-time libraries which are optimized for various functional requirements. These libraries support most of the ANSI C function calls.

Library File | Description
C51S.LIB | Small model library without floating-point arithmetic
C51FPS.LIB | Small model floating-point arithmetic library
C51C.LIB | Compact model library without floating-point arithmetic
C51FPC.LIB | Compact model floating-point arithmetic library
C51L.LIB | Large model library without floating-point arithmetic
C51FPL.LIB | Large model floating-point arithmetic library
80C751.LIB | Library for use with the Signetics 8xC751 and derivatives.

Several library modules are provided in source code form. These routines are used to perform low-level hardware-related I/O for the stream I/O functions. You can find the source for these routines in the LIB directory. You may modify these source files and substitute them for the library routines. By using these routines, you can quickly adapt the library to perform (using any hardware I/O device available in your target) stream I/O.


Standard Types

The C51 standard library contains definitions for a number of standard types which may be used by the library routines. These standard types are declared in include files which you may access from your C programs.

jmp_buf

The jmp_buf type is defined in setjmp.h and specifies the buffer used by the setjmp and longjmp routines to save and restore the program environment. The jmp_buf type is defined as follows:

#define _JBLEN   7
typedef char jmp_buf[_JBLEN];
va_list

The va_list array type is defined in stdarg.h. This type holds data required by the va_arg and va_end routines. The va_list type is defined as follows:

typedef char *va_list;


Absolute Memory Access Macros

The C51 standard library contains definitions for a number of macros that allow you to access explicit memory addresses. These macros are defined in absacc.h. Each of these macros is defined to be used like an array.

CBYTE

The CBYTE macro allows you to access individual bytes in the program memory of the 8051 and is defined as follows:

#define CBYTE ((unsigned char volatile code *)0)

You may use this macro in your programs as follows:

rval = CBYTE [0x0002];

to read the contents of the byte in program memory at address 0002h.

CWORD

The CWORD macro allows you to access individual words in the program memory of the 8051 and is defined as follows:

#define CWORD ((unsigned int volatile code *) 0)

You may use this macro in your programs as follows:

rval = CWORD [0x0002];

to read the contents of the word in program memory at address 0004h (2 × sizeof (unsigned int) = 4).

NOTE
The index used with this macro does not represent the memory address of the integer value. To obtain the memory address, you must multiply the index by the sizeof an integer (2 bytes).

DBYTE

The DBYTE macro allows you to access individual bytes in the internal data memory of the 8051 and is defined as follows:

#define DBYTE ((unsigned char volatile idata *) 0)

You may use this macro in your programs as follows:

rval = DBYTE [0x0002];
DBYTE [0x0002] = 5;

to read or write the contents of the byte in internal data memory at address 0002h.

DWORD

The DWORD macro allows you to access individual words in the internal data memory of the 8051 and is defined as follows:

#define DWORD ((unsigned int volatile idata *) 0)

You may use this macro in your programs as follows:

rval = DWORD [0x0002];
DWORD [0x0002] = 57;

to read or write the contents of the word in internal data memory at address 0004h (2 × sizeof (unsigned int) = 4).

NOTE
The index used with this macro does not represent the memory address of the integer value. To obtain the memory address, you must multiply the index by the sizeof an integer (2 bytes).

PBYTE

The PBYTE macro allows you to access individual bytes in one page of the external data memory of the 8051 and is defined as follows:

#define PBYTE ((unsigned char volatile pdata *) 0)

You may use this macro in your programs as follows:

rval = PBYTE [0x0002];
PBYTE [0x0002] = 38;

to read or write the contents of the byte in pdata memory at address 0002h.

PWORD

The PWORD macro allows you to access individual words in one page of the external data memory of the 8051 and is defined as follows:

#define PWORD ((unsigned int volatile pdata*) 0)

You may use this macro in your programs as follows:

rval = PWORD [0x0002];
PWORD [0x0002] = 57;

to read or write the contents of the word in pdata memory at address 0004h (2 × sizeof (unsigned int) = 4).

NOTE
The index used with this macro does not represent the memory address of the integer value. To obtain the memory address, you must multiply the index by the sizeof an integer (2 bytes).

XBYTE

The XBYTE macro allows you to access individual bytes in the external data memory of the 8051 and is defined as follows:

#define XBYTE ((unsigned char volatile xdata*) 0)

You may use this macro in your programs as follows:

rval = XBYTE [0x0002];
XBYTE [0x0002] = 57;

to read or write the contents of the byte in external data memory at address 0002h.

XWORD

The XWORD macro allows you to access individual words in the external data memory of the 8051 and is defined as follows:

#define XWORD ((unsigned int volatile xdata*) 0)

You may use this macro in your programs as follows:

rval = XWORD [2];
XWORD [2] = 57;

to read or write the contents of the word in external data memory at address 0004h (2 × sizeof (unsigned int) = 4).

NOTE
The index used with this macro does not represent the memory address of the integer value. To obtain the memory address, you must multiply the index by the sizeof an integer (2 bytes).


Routines by Category

This sections gives a brief overview of the major categories of routines available in the C51 standard library.

NOTE
Many of the routines in the C51 standard library are reentrant, intrinsic, or both. These specifications are listed under attributes in the following tables. Unless otherwise noted, routines are non-reentrant and non-intrinsic.

Buffer Manipulation
Routine | Attributes | Description
memccpy |  | Copies data bytes from one buffer to another until a specified character or specified number of characters has been copied.
memchr | reentrant | Returns a pointer to the first occurrence of a specified character in a buffer.
memcmp | reentrant | Compares a given number of characters from two different buffers.
memcpy | reentrant | Copies a specified number of data bytes from one buffer to another.
memmove | reentrant | Copies a specified number of data bytes from one buffer to another.
memset | reentrant | Initializes a specified number of data bytes in a buffer to a specified character value.

The buffer manipulation routines are used to work on memory buffers on a character-by-character basis. A buffer is an array of characters like a string, however, a buffer is usually not terminated with a null character ('\0'). For this reason, these routines require a buffer length or count argument.

All of these routines are implemented as functions. Function prototypes are included in the string.h include file.


Character Conversion and Classification

Routine | Attributes | Description
isalnum | reentrant | Tests for an alphanumeric character.
isalpha | reentrant | Tests for an alphabetic character.
iscntrl | reentrant | Tests for a Control character.
isdigit | reentrant | Tests for a decimal digit.
isgraph | reentrant | Tests for a printable character with the exception of space.
islower | reentrant | Tests for a lowercase alphabetic character.
isprint | reentrant | Tests for a printable character.
ispunct | reentrant | Tests for a punctuation character.
isspace | reentrant | Tests for a whitespace character.
isupper | reentrant | Tests for an uppercase alphabetic character.
isxdigit | reentrant | Tests for a hexadecimal digit.
toascii | reentrant | Converts a character to an ASCII code.
toint | reentrant | Converts a hexadecimal digit to a decimal value.
tolower | reentrant | Tests a character and converts it to lowercase if it is uppercase.
_tolower | reentrant | Unconditionally converts a character to lowercase.
toupper | reentrant | Tests a character and converts it to uppercase if it is lowercase.
_toupper | reentrant | Unconditionally converts a character to uppercase.

The character conversion and classification routines allow you to test individual characters for a variety of attributes and convert characters to different formats.

The _tolower, _toupper, and toascii routines are implemented as macros. All other routines are implemented as functions. All macro definitions and function prototypes are found in the ctype.h include file.


Data Conversion

Routine | Attributes | Description
abs | reentrant | Generates the absolute value of an integer type.
atof / atof517 |  | Converts a string to a float.
atoi |  | Converts a string to an int.
atol |  | Converts a string to a long.
cabs | reentrant | Generates the absolute value of a character type.
labs | reentrant | Generates the absolute value of a long type.
strtod/ strtod517 |  | Converts a string to a float.
strtol |  | Converts a string to a long.
strtoul |  | Converts a string to an unsigned long.

The data conversion routines convert strings of ASCII characters to numbers. All of these routines are implemented as functions and most are prototyped in the include file stdlib.h. The abs, cabs, and labs functions are prototyped in the math.h include file. The atof517 function is prototyped in the include file 80517.h.


Math

Routine | Attributes | Description
acos / acos517 |  | Calculates the arc cosine of a specified number.
asin / asin517 |  | Calculates the arc sine of a specified number.
atan / atan517 |  | Calculates the arc tangent of a specified number.
atan2 |  | Calculates the arc tangent of a fraction.
ceil |  | Finds the integer ceiling of a specified number.
cos / cos517 |  | Calculates the cosine of a specified number.
cosh |  | Calculates the hyperbolic cosine of a specified number.
exp / exp517 |  | Calculates the exponential function of a specified number.
fabs | reentrant | Finds the absolute value of a specified number.
floor |  | Finds the largest integer less than or equal to a specified number.
fmod |  | Calculates the floating-point remainder.
log / log517 |  | Calculates the natural logarithm of a specified number.
log10 / log10517 |  | Calculates the common logarithm of a specified number.
modf |  | Generates integer and fractional components of a specified number.
pow |  | Calculates a value raised to a power.
rand | reentrant | Generates a pseudo random number.
sin / sin517 |  | Calculates the sine of a specified number.
sinh |  | Calculates the hyperbolic sine of a specified number.
srand |  | Initializes the pseudo random number generator.
sqrt / sqrt517 |  | Calculates the square root of a specified number.
tan / tan517 |  | Calculates the tangent of a specified number.
tanh |  | Calculates the hyperbolic tangent of a specified number.
_chkfloat_ | intrinsic, reentrant | Checks the status of float numbers.
_crol_ | intrinsic, reentrant | Rotates an unsigned char left a specified number of bits.
_cror_ | intrinsic, reentrant | Rotates an unsigned char right a specified number of bits.
_irol_ | intrinsic, reentrant | Rotates an unsigned int left a specified number of bits.
_iror_ | intrinsic, reentrant | Rotates an unsigned int right a specified number of bits.
_lrol_ | intrinsic, reentrant | Rotates an unsigned long left a specified number of bits.
_lror_ | intrinsic, reentrant | Rotates an unsigned long right a specified number of bits.

The math routines perform common mathematical calculations. Most of these routines work with floating-point values and therefore include the floating-point libraries and support routines.

All of these routines are implemented as functions. Most are prototyped in the include file math.h. Functions which end in 517 (acos517, asin517, atan517, cos517, exp517, log517, log10517, sin517, sqrt517, and tan517) are prototyped in the 80517.h include file. The rand and srand functions are prototyped in the stdlib.h include file.

The _chkfloat_, _crol_, _cror_, _irol_, _iror_, _lrol_, and _lror_ functions are prototyped in the intrins.h include file.


Memory Allocation

Routine | Attributes | Description
calloc |  | Allocates storage for an array from the memory pool.
free |  | Frees a memory block that was allocated using calloc, malloc, or realloc.
init_mempool |  | Initializes the memory location and size of the memory pool.
malloc |  | Allocates a block from the memory pool.
realloc |  | Reallocates a block from the memory pool.

The memory allocation functions provide you with a means to specify, allocate, and free blocks of memory from a memory pool. All memory allocation functions are implemented as functions and are prototyped in the stdlib.h include file.

Before using any of these functions to allocate memory, you must first specify, using the init_mempool routine, the location and size of a memory pool from which subsequent memory requests are satisfied.

The calloc and malloc routines allocate blocks of memory from the pool. The calloc routine allocates an array with a specified number of elements of a given size and initializes the array to 0. The malloc routine allocates a specified number of bytes.

The realloc routine changes the size of an allocated block, while the free routine returns a previously allocated memory block to the memory pool.


Stream Input and Output

Routine | Attributes | Description
getchar | reentrant | Reads and echoes a character using the _getkey and putchar routines.
_getkey |  | Reads a character using the 8051 serial interface.
gets |  | Reads and echoes a character string using the getchar routine.
printf / printf517 |  | Writes formatted data using the putchar routine.
putchar |  | Writes a character using the 8051 serial interface.
puts | reentrant | Writes a character string and newline ('\n') character using the putchar routine.
scanf |  | Reads formatted data using the getchar routine.
sprintf / sprintf517 |  | Writes formatted data to a string.
sscanf / sscanf517 |  | Reads formatted data from a string.
ungetchar |  | Places a character back into the getchar input buffer.
vprintf |  | Writes formatted data using the putchar function.
vsprintf |  | Writes formatted data to a string.

The stream input and output routines allow you to read and write data to and from the 8051 serial interface or a user-defined I/O interface. The default _getkey and putchar functions found in the C51 library read and write characters using the 8051 serial interface. You can find the source for these functions in the LIB directory. You may modify these source files and substitute them for the library routines. When this is done, other stream functions then perform input and output using the new _getkey and putchar routines.

If you want to use the existing _getkey and putchar functions, you must first initialize the 8051 serial port. If the serial port is not properly initialized, the default stream functions do not function. Initializing the serial port requires manipulating special function registers SFRs of the 8051. The include file reg51.h contains definitions for the required SFRs.

The following example code must be executed immediately after reset, before any stream functions are invoked.

Example
.
.
.
#include <reg51.h>
.
.
.
SCON = 0x50;          /* Setup serial port control register */
                      /* Mode 1: 8-bit uart var. baud rate */
                      /* REN: enable receiver */

PCON &= 0x7F;         /* Clear SMOD bit in power ctrl reg */
                      /* This bit doubles the baud rate */

TMOD &= 0xCF          /* Setup timer/counter mode register */
                      /* Clear M1 and M0 for timer 1 */
TMOD |= 0x20;         /* Set M1 for 8-bit autoreload timer */

TH1 = 0xFD;           /* Set autoreload value for timer 1 */
                      /* 9600 baud with 11.0592 MHz xtal */

TR1 = 1;              /* Start timer 1 */

TI = 1;               /* Set TI to indicate ready to xmit */
.
.
.

The stream routines treat input and output as streams of individual characters. There are routines that process characters as well as functions that process strings. Choose the routines that best suit your requirements.

All of these routines are implemented as functions. Most are prototyped in the stdio.h include file. The printf517, scanf517, sprintf517, and sscanf517 functions are prototyped in the 80517.h include file.


String Manipulation

Routine | Attributes | Description
strcat |  | Concatenates two strings.
strchr | reentrant | Returns a pointer to the first occurrence of a specified character in a string.
strcmp | reentrant | Compares two strings.
strcpy | reentrant | Copies one string to another.
strcspn |  | Returns the index of the first character in a string that matches any character in a second string.
strlen | reentrant | Returns the length of a string.
strcat |  | Concatenates up to a specified number of characters from one string to another.
strncmp |  | Compares two strings up to a specified number of characters.
strncpy |  | Copies up to a specified number of characters from one string to another.
strpbrk |  | Returns a pointer to the first character in a string that matches any character in a second string.
strpos | reentrant | Returns the index of the first occurrence of a specified character in a string.
strrchr | reentrant | Returns a pointer to the last occurrence of a specified character in a string.
strrpbrk |  | Returns a pointer to the last character in a string that matches any character in a second string.
strrpos | reentrant | Returns the index of the last occurrence of a specified character in a string.
strspn |  | Returns the index of the first character in a string that does not match any character in a second string.

The string routines are implemented as functions and are prototyped in the string.h include file. They perform the following operations:

  • Copying strings
  • Appending one string to the end of another
  • Comparing two strings
  • Locating one or more characters from a specified set in a string

All string functions operate on null-terminated character strings. To work on non-terminated strings, use the buffer manipulation routines described earlier in this section.


Variable-length Argument Lists

Routine | Attributes | Description
va_arg | reentrant | Retrieves an argument from an argument list.
va_end | reentrant | Resets an argument pointer.
va_start | reentrant | Sets a pointer to the beginning of an argument list.

The variable-length argument list routines are implemented as macros and are defined in the stdarg.h include file. These routines provide you with a portable method of accessing arguments in a function that takes a variable number of arguments. These macros conform to the ANSI C Standard for variable-length argument lists.


Miscellaneous

Routine | Attributes | Description
setjmp | reentrant | Saves the current stack condition and program address.
longjmp | reentrant | Restores the stack condition and program address.
_nop_ | intrinsic, reentrant | Inserts an 8051 NOP instruction.
_testbit_ | intrinsic, reentrant | Tests the value of a bit and clears it to 0.

Routines found in the miscellaneous category do not fit easily into any other library routine category. The setjmp and longjmp routines are implemented as functions and are prototyped in the setjmp.h include file.

The _nop_ and _testbit_ routines are used to direct the compiler to generate a NOP instruction and a JBC instruction respectively. These routines are prototyped in the intrins.h include file.


Include Files

The include files that are provided with the C51 standard library are found in the INC subdirectory. These files contain constant and macro definitions, type definitions, and function prototypes. The following sections describe the use and contents of each include file. Macros and functions included in the file are listed as well.

8051 Special Function Register Include Files

The C51 library provides you with a number of include files that define manifest constants for the special function registers found on many 8051 derivatives. These files are listed below:

REG151S.H
REG152.H
REG320.H
REG410.H
REG451.H
REG452.H
REG509.H
REG51.H
REG515.H
REG515A.H
REG515C.H
REG517.H
REG517A.H
REG51F.H
REG51G.H
REG51GB.H
REG52.H
REG552.H
REG592.H
REG781.H


Reference

The following pages constitute the C51 standard library reference. The routines included in the standard library are described here in alphabetical order and each is divided into several sections:

Summary:
Briefly describes the routine's effect, lists include file(s) containing its declaration and prototype, illustrates the syntax, and describes any arguments.

Description:
Provides you with a detailed description of the routine and how it is used.

Return Value:
Describes the value returned by the routine.

See Also:
Names related routines.

Example:
Gives a function or program fragment demonstrating proper use of the function.


abs

#include <math.h>
int abs (int val);   /* number to take absolute value of */

Description:
The abs function determines the absolute value of the integer argument val.

Return Value:
The abs function returns the absolute value of val.

Attributes:
reentrant

See Also:
cabs, fabs, labs

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_abs (void)  {
  int x;
  int y;

  x = -42;

  y = abs (x);

  printf ("ABS(%d) = %d\n", x, y);
}


acos / acos517

#include <math.h>
float acos (float x);   /* number to calculate arc cosine of */

Description:
The acos function calculates the arc cosine of the floating-point number x. The value of x must be between -1 and 1. The floating-point value returned by acos is a number in the 0 to π range.

The acos517 function is identical to acos, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The acos function returns the arc cosine of x.

Attributes:
non-reentrant

See Also:
asin / asin517, atan / atan517, atan2

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_acos (void)  {
  float x;
  float y;

  for (x = -1.0; x <= 1.0; x += 0.1)  {
    y = acos (x);

    printf ("ACOS(%f) = %f\n", x, y);


asin / asin517

#include <math.h>
float asin (float x);   /* number to calculate arc sine of */

Description:
The asin function calculates the arc sine of the floating-point number x. The value of x must be in the range -1 to 1. The floating-point value returned by asin is a number in the -π/2 to π/2 range.

The asin517 function is identical to asin, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The asin function returns the arc sine of x.

Attributes:
non-reentrant

See Also:
acos / acos517, atan / atan517, atan2

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_asin (void)  {
  float x;
  float y;

  for (x = -1.0; x <= 1.0; x += 0.1)  {
    y = asin (x);

    printf ("ASIN(%f) = %f\n", x, y);


assert

#include <assert.h>
void assert (expression);

Description:
The assert macro tests expression and prints a diagnostic message using the printf library routine if it is false.

Return Value:
None.

Attributes:
non-reentrant

Example
#include <assert.h>
#include <stdio.h>

void check_parms (
  char *string)
{
  assert (string != NULL);    /* check for NULL ptr */
  printf ("String %s is OK\n", string);


atan / atan517

#include <math.h>
float atan (float x);   /* number to calculate arc tangent of */

Description:
The atan function calculates the arc tangent of the floating-point number x. The floating-point value returned by atan is a number in the -π/2 to π/2 range.

The atan517 function is identical to atan, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The atan function returns the arc tangent of x.

Attributes:
non-reentrant

See Also:
acos / acos517, asin / asin517, atan2

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_atan (void)  {
  float x;
  float y;

  for (x = -10.0; x <= 10.0; x += 0.1)  {
    y = atan (x);

    printf ("ATAN(%f) = %f\n", x, y);


atan2

#include <math.h>
float atan2 (float y,    /* y = denominator for arc tangent */
             float x);   /* x = numerator for arc tangent   */

Description:
The atan2 function calculates the arc tangent of the floating-point ratio y / x. This function uses the signs of both x and y to determine the quadrant of the return value. The floating-point value returned by atan2 ia a number in the -π to π range.

Return Value:
The atan2 function returns the arc tangent of y / x.

Attributes:
non-reentrant

See Also:
acos / acos517, asin / asin517, atan / atan517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_atan2 ()  {
  float x;
  float y;
  float z;

  x = -1.0;

  for (y = -10.0; y < 10.0; y += 0.1)  {
    z = atan2 (y,x);

    printf ("ATAN2(%f/%f) = %f\n", y, x, z);
  }

  /* z approaches -pi as y goes from -10 to 0 */
  /* z approaches +pi as y goes from +10 to 0 */


atof / atof517

#include <stdlib.h>
float atof (void *string);   /* string to convert */

Description:
The atof function converts string into a floating-point value. The input string is a sequence of characters that can be interpreted as a floating-point number. This function stops processing characters from string at the first one it cannot recognize as part of the number.

The atof517 function is identical to atof, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

The atof function requires string to have the following format:
[ {+ | -} ] digits [. digits] [{e | E} [ {+ | -} ] digits ]

where:
digitsmay be one or more decimal digits.

Return Value:
The atof function returns the floating-point value that is produced by interpreting the characters in string as a number.

Attributes:
non-reentrant

See Also:
atoi, atol

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_atof (void)  {
  float f;
  char s [] = "1.23";

  f = atof (s);
  printf ("ATOF(%s) = %f\n", s, f);


atoi

#include <stdlib.h>
int atoi (void *string);   /* string to convert */

Description:
The atoi function converts string into an integer value. The input string is a sequence of characters that can be interpreted as an integer. This function stops processing characters from string at the first one it cannot recognize as part of the number.

The atoi function requires string to have the following format:

[whitespace] [{+ | -}] digits

where:
digitsmay be one or more decimal digits.

Return Value:
The atoi function returns the integer value that is produced by interpreting the characters in string as a number.

Attributes:
non-reentrant

See Also:
atof / atof517, atol

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_atoi (void)  {
  int i;
  char s [] = "12345";

  i = atoi (s);
  printf ("ATOI(%s) = %d\n", s, i);


atol

#include <stdlib.h>
long atol (void *string);   /* string to convert */

Description:
The atol function converts string into a long integer value. The input string is a sequence of characters that can be interpreted as a long. This function stops processing characters from string at the first one it cannot recognize as part of the number.

The atol function requires string to have the following format:

[whitespace] [{+ | -}] digits

where:
digitsmay be one or more decimal digits.

Return Value:
The atol function returns the long integer value that is produced by interpreting the characters in string as a number.

Attributes:
non-reentrant

See Also:
atof / atof517, atoi

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_atol (void)  {
  long l;
  char s [] = "8003488051";

  l = atol (s);
  printf ("ATOL(%s) = %ld\n", s, l);


cabs

#include <math.h>
char cabs (char val);   /* character to take absolute value of */

Description:
The cabs function determines the absolute value of the character argument val.

Return Value:
The cabs function returns the absolute value of val.

Attributes:
reentrant

See Also:
abs , fabs, labs

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_cabs (void)  {
  char x;
  char y;

  x = -23;

  y = cabs (x);

  printf ("CABS(%bd) = %bd\n", x, y);


calloc

#include <stdlib.h>
void *calloc (unsigned int num,    /* number of items     */
              unsigned int len);   /* length of each item */

Description:
The calloc function allocates memory for an array of num elements. Each element in the array occupies len bytes and is initialized to 0. The total number of bytes of memory allocated is num × len.

NOTE
Source code is provided for this routine in the lib directory. You can modify the source to customize this function for your hardware environment.

Return Value:
The calloc function returns a pointer to the allocated memory or a null pointer if the memory allocation request cannot be satisfied.

Attributes:
non-reentrant

See Also:
free, init_mempool, malloc, realloc

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_calloc (void)  {
  int xdata *p;           /* ptr to array of 100 ints */

  p = calloc (100, sizeof (int));

  if (p == NULL)
  printf ("Error allocating array\n");
  else
    printf ("Array address is %p\n", (void *) p);


ceil

#include <math.h>
float ceil (float val);   /* number to calculate ceiling for */

Description:
The ceil function calculates the smallest integer value that is greater than or equal to val.

Return Value:
The ceil function returns a float that contains the smallest integer value that is not less than val.

Attributes:
non-reentrant

See Also:
floor

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_ceil (void)  {
  float x;
  float y;

  x = 45.998;
  y = ceil (x);

  printf ("CEIL(%f) = %f\n", x, y);

  /* output is "CEIL(45.998) = 46" */


_chkfloat_

#include <intrins.h>
unsigned char _chkfloat_ (float val);   /* number for error checking */

Description:
The _chkfloat_ function checks the status of a floating-point number.

Return Value:
The _chkfloat_ function returns an unsigned char that contains the following status information:

Return Value | Meaning
0 | Standard floating-point numbers
1 | Floating-point value 0
2 | +INF (positive overflow)
3 | -INF (negative overflow)
4 | NaN (Not a Number) error status

Attributes:
reentrant, intrinsic

Example
#include <intrins.h>
#include <stdio.h>                      /* for printf */

char _chkfloat_ (float);

float f1, f2, f3;

void tst_chkfloat (void)  {
  f1 = f2 * f3;

  switch (_chkfloat_ (f1))  {
    case 0:
      printf ("result is a number\n"); break;
    case 1:
      printf ("result is zero\n");     break;
    case 2:
      printf ("result is +INF\n");     break;
    case 3:
      printf ("result is -INF\n");     break;
    case 4:
      printf ("result is NaN\n");      break;


cos / cos517

#include <math.h>
float cos (float x);   /* number to calculate cosine for */

Description:
The cos function calculates the cosine of the floating-point value x. The value of x must be between -65535 and 65535. Values outside this range result in an NaN error.

The cos517 function is identical to cos, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The cos function returns the cosine for the value x.

Attributes:
non-reentrant

See Also:
sin / sin517, tan / tan517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_cos (void)  {
  float x;
  float y;

  for (x = 0; x < (2 * 3.1415); x += 0.1)  {
    y = cos (x);

    printf ("COS(%f) = %f\n", x, y);


cosh

#include <math.h>
float cosh (float x);   /* value for hyperbolic cos function */

Description:
The cosh function calculates the hyperbolic cosine of the floating-point value x.

Return Value:
The cosh function returns the hyperbolic cosine for the value x.

Attributes:
non-reentrant

See Also:
sinh, tanh

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_cosh (void)  {
  float x;
  float y;

  for (x = 0; x < (2 * 3.1415); x += 0.1)  {
    y = cosh (x);

    printf ("COSH(%f) = %f\n", x, y);


_crol_

#include <intrins.h>
unsigned char _crol_ (unsigned char c,    /* character to rotate left */
                      unsigned char b);   /* bit positions to rotate  */

Description:
The _crol_ routine rotates the bit pattern for the character c left b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _crol_ routine returns the rotated value of c.

Attributes:
reentrant, intrinsic

See Also:
_cror_, _irol_, _iror_, _lrol_, _lror_

Example
#include <intrins.h>

void tst_crol (void)  {
  char a;
  char b;

  a = 0xA5;

  b = _crol_(a,3);                   /* b now is 0x2D */


_cror_

#include <intrins.h>
unsigned char _cror_ (unsigned char c,    /* character to rotate right */
                      unsigned char b);   /* bit positions to rotate   */

Description:
The _cror_ routine rotates the bit pattern for the character c right b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _cror_ routine returns the rotated value of c.

Attributes:
reentrant, intrinsic

See Also:
_crol_, _irol_, _iror_, _lrol_, _lrol_

Example
#include <intrins.h>

void tst_cror (void)  {
  char a;
  char b;

  a = 0xA5;

  b = _crol_(a,1);                   /* b now is 0xD2 */


exp / exp517

#include <math.h>
float exp (float x);    /* power to use for ex function */

Description:
The exp function calculates the exponential function for the floating-point value x.

The exp517 function is identical to exp, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The exp function returns the floating-point value ex.

Attributes:
non-reentrant

See Also:
log / log517, log10 / log10517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_exp (void)  {
  float x;
  float y;

  x = 4.605170186;

  y = exp (x);                             /* y = 100 */

  printf ("EXP(%f) = %f\n", x, y);


fabs

#include <math.h>
float fabs (float val);   /* number to calc absolute value for */

Description:
The fabs function determines the absolute value of the floating-point number val.

Return Value:
The fabs function returns the absolute value of val.

Attributes:
reentrant

See Also:
abs , cabs, labs

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_fabs (void)  {
  float x;
  float y;

  x = 10.2;
  y = fabs (x);
  printf ("FABS(%f) = %f\n", x, y);

  x = -3.6;
  y = fabs (x);
  printf ("FABS(%f) = %f\n", x, y);


floor

#include <math.h>
float floor (float val);   /* value for floor function */

Description:
The floor function calculates the largest integer value that is less than or equal to val.

Return Value:
The floor function returns a float that contains the largest integer value that is not greater than val.

Attributes:
non-reentrant

See Also:
ceil

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_floor (void)  {
  float x;
  float y;

  x = 45.998;

  y = floor (x);

  printf ("FLOOR(%f) = %f\n", x, y);     /* prints 45 */


fmod

#include <math.h>
float fmod (float  x,    /* value to divide */
            float  y);   /* divisor         */

Description:
The fmod function returns a value f such that f has the same sign as x, the absolute value of f is less than the absolute value of y, and there exists an integer k such that k*y+f equals x. If the quotient x / y cannot be represented, the result is undefined.

Return Value:
The fmod function returns the floating-point remainder of x / y.

Attributes:
non-reentrant

See Also:
ceil, floor

Example
#include <math.h>
#include <stdio.h>                         /* for printf */
void tst_fmod (void)  {
  float f;
  f = fmod (-15.0, 4.0);
  printf ("fmod (-15.0, 4.0) = %f\n", f);
}
#include <reg51.h>
void main (void)  {
    SCON  = 0x50;              /* SCON: mode 1, 8-bit UART, enable rcvr    */
    TMOD |= 0x20;               /* TMOD: timer 1, mode 2, 8-bit reload      */
    TH1   = 221;                /* TH1:  reload value for 1200 baud @ 16MHz */
    TR1   = 1;                  /* TR1:  timer 1 run                        */
    TI    = 1;                  /* TI:   set TI to send first char of UART  */
 tst_fmod ();


free

#include <stdlib.h>
void free (void xdata *p);   /* block to free */

Description:
The free function returns a memory block to the memory pool. The p argument points to a memory block allocated with the calloc, malloc, or realloc functions. Once it has been returned to the memory pool by the free function, the block is available for subsequent allocation.

If p is a null pointer, it is ignored.

NOTE
Source code for this routine is located in the \c51\lib directory. You may modify the source to customize this function for your particular hardware environment.

Return Value:
None.

Attributes:
non-reentrant

See Also:
calloc, init_mempool, malloc, realloc

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_free (void)  {
  void *mbuf;

  printf ("Allocating memory\n");
  mbuf = malloc (1000);

  if (mbuf == NULL)  {
    printf ("Unable to allocate memory\n");
  }
  else  {
      free (mbuf);
      printf ("Memory free\n");


getchar

#include <stdio.h>
char getchar (void);

Description:
The getchar function reads a single character from the input stream using the _getkey function. The character read is then passed to the putchar function to be echoed.

NOTE
This function is implementation-specific and is based on the operation of the _getkey and/or putchar functions. These functions, as provided in the standard library, read and write characters using the serial port of the 8051. Custom functions may use other I/O devices.

Return Value:
The getchar function returns the character read.

Attributes:
reentrant

See Also:
_getkey, putchar, ungetchar

Example
#include <stdio.h>

void tst_getchar (void)  {
  char c;

  while ((c = getchar ()) != 0x1B)  {
    printf ("character = %c %bu %bx\n", c, c, c);


_getkey

#include <stdio.h>
char _getkey (void);

Description:
The _getkey function waits for a character to be received from the serial port.

NOTE
This routine is implementation-specific, and its function may deviate from that described above. Source is included for the _getkey and putchar functions which may be modified to provide character level I/O for any hardware device.

Return Value:
The _getkey routine returns the received character.

Attributes:
non-reentrant

See Also:
getchar, putchar, ungetchar

Example
#include <stdio.h>

void tst_getkey (void)  {
  char c;

  while ((c = _getkey ()) != 0x1B)  {
    printf ("key = %c %bu %bx\n", c, c, c);


gets

#include <stdio.h>
char *gets (char *string,   /* string to read             */
            int len);       /* maximum characters to read */

Description:
The gets function calls the getchar function to read a line of characters into string. The line consists of all characters up to and including the first newline character ('\n'). The newline character is replaced by a null character ('\0') in string.

The len argument specifies the maximum number of characters that may be read. If len characters are read before a newline is encountered, the gets function terminates string with a null character and returns.

NOTE
This function is implementation-specific and is based on the operation of the _getkey and/or putchar functions. These functions, as provided in the standard library, read and write characters using the serial port of the 8051. Custom functions may use other I/O devices.

Return Value:
The gets function returns string.

Attributes:
non-reentrant

See Also:
printf / printf517, puts, scanf

Example
#include <stdio.h>

void tst_gets (void)  {
  xdata char buf [100];

  do  {
    gets (buf, sizeof (buf));
    printf ("Input string \"%s\"", buf);
  } while (buf [0] != '\0');


init_mempool

#include <stdlib.h>
void init_mempool (void xdata *p,        /* start of memory pool  */
                   unsigned int size);   /* length of memory pool */

Description:
The init_mempool function initializes the memory management routines and provides the starting address and size of the memory pool. The p argument points to a memory area in xdata which is managed using the calloc, free, malloc, and realloc library functions. The size argument specifies the number of bytes to use for the memory pool.

NOTE
This function must be used to setup the memory pool before any other memory management functions (calloc, free, malloc, realloc) can be called. Call the init_mempool function only once at the beginning of your program.

Source code is provided for this routine in the \lib directory. You can modify the source to customize this function for your hardware environment.

Return Value:
None.

Attributes:
non-reentrant

See Also:
calloc, free, malloc, realloc

Example
#include <stdlib.h>

void tst_init_mempool (void)  {
  xdata void *p;
  int i;

  init_mempool (&XBYTE [0x2000], 0x1000);
/* initialize memory pool at xdata 0x2000
   for 4096 bytes */

  p = malloc (100);
  for (i = 0; i < 100; i++) ((char *) p)[i] = i;
  free (p);


_irol_

#include <intrins.h>
unsigned int _irol_ (unsigned int i,    /* integer to rotate left  */
                     unsigned char b);  /* bit positions to rotate */

Description:
The _irol_ routine rotates the bit pattern for the integer i left b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _irol_ routine returns the rotated value of i.

Attributes:
reentrant, intrinsic

See Also:
_cror_, _crol_, _iror_, _lrol_, _lror_

Example
#include <intrins.h>

void tst_irol (void)  {
  int a;
  int b;

  a = 0xA5A5;

  b = _irol_(a,3);                 /* b now is 0x2D2D */


_iror_

#include <intrins.h>
unsigned int _iror_ (unsigned int i,     /* integer to rotate right */
                     unsigned char b);   /* bit positions to rotate */

Description:
The _iror_ routine rotates the bit pattern for the integer i right b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _iror_ routine returns the rotated value of i.

Attributes:
reentrant, intrinsic

See Also:
_cror_, _crol_, _irol_, _lrol_, _lror_

Example
#include <intrins.h>

void tst_iror (void)  {
  int a;
  int b;

  a = 0xA5A5;

  b = _irol_(a,1);                 /* b now is 0xD2D2 */


isalnum

#include <ctype.h>
bit isalnum (char c);   /* character to test */

Description:
The isalnum function tests c to determine if it is an alphanumeric character ('A'-'Z', 'a'-'z', '0'-'9').

Return Value:
The isalnum function returns a value of 1 if c is an alphanumeric character or a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isalnum (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isalnum (i) ? "YES" : "NO");

    printf ("isalnum (%c) %s\n", i, p);


isalpha

#include <ctype.h>
bit isalpha (char c);   /* character to test */

Description:
The isalpha function tests c to determine if it is an alphabetic character ('A'-'Z' or 'a'-'z').

Return Value:
The isalpha function returns a value of 1 if c is an alphabetic character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isalpha (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isalpha (i) ? "YES" : "NO");

    printf ("isalpha (%c) %s\n", i, p);


iscntrl

#include <ctype.h>
bit iscntrl (char c);   /* character to test */

Description:
The iscntrl function tests c to determine if it is a control character (0x00-0x1F or 0x7F).

Return Value:
The iscntrl function returns a value of 1 if c is a control character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_iscntrl (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (iscntrl (i) ? "YES" : "NO");

    printf ("iscntrl (%c) %s\n", i, p);


isdigit

#include <ctype.h>
bit isdigit (char c);   /* character to test */

Description:
The isdigit function tests c to determine if it is a decimal digit ('0'-'9').

Return Value:
The isdigit function returns a value of 1 if c is a decimal digit and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isdigit (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isdigit (i) ? "YES" : "NO");

    printf ("isdigit (%c) %s\n", i, p);


isgraph

#include <ctype.h>
bit isgraph (char c);   /* character to test */

Description:
The isgraph function tests c to determine if it is a printable character (not including space). The character values tested for are 0x21-0x7E.

Return Value:
The isgraph function returns a value of 1 if c is a printable character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, islower, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isgraph (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isgraph (i) ? "YES" : "NO");

    printf ("isgraph (%c) %s\n", i, p);


islower

#include <ctype.h>
bit islower (char c);   /* character to test */

Description:
The islower function tests c to determine if it is a lowercase alphabetic character ('a'-'z').

Return Value:
The islower function returns a value of 1 if c is a lowercase letter and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, isprint, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_islower (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (islower (i) ? "YES" : "NO");

    printf ("islower (%c) %s\n", i, p);


isprint

#include <ctype.h>
bit isprint (char c);   /* character to test */

Description:
The isprint function tests c to determine if it is a printable character (0x20-0x7E).

Return Value:
The isprint function returns a value of 1 if c is a printable character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, ispunct, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isprint (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isprint (i) ? "YES" : "NO");

    printf ("isprint (%c) %s\n", i, p);


ispunct

#include <ctype.h>
bit ispunct (char c);   /* character to test */

Description:
The ispunct function tests c to determine if it is a punctuation character. The following symbols are punctuation characters:

! " # $ % & ' (
) * + , - . / :
; < = > ? @ [ \
] ^ _ ` { | } ~

Return Value:
The ispunct function returns a value of 1 if c is a punctuation character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, isspace, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_ispunct (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (ispunct (i) ? "YES" : "NO");

    printf ("ispunct (%c) %s\n", i, p);


isspace

#include <ctype.h>
bit isspace (char c);   /* character to test */

Description:
The isspace function tests c to determine if it is a whitespace character (0x09-0x0D or 0x20).

Return Value:
The isspace function returns a value of 1 if c is a whitespace character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isupper, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isspace (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isspace (i) ? "YES" : "NO");

    printf ("isspace (%c) %s\n", i, p);


isupper

#include <ctype.h>
bit isupper (char c);   /* character to test */

Description:
The isupper function tests c to determine if it is an uppercase alphabetic character ('A'-'Z').

Return Value:
The isupper function returns a value of 1 if c is an uppercase character and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isxdigit

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isupper (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isupper (i) ? "YES" : "NO");

    printf ("isupper (%c) %s\n", i, p);


isxdigit

#include <ctype.h>
bit isxdigit (char c);   /* character to test */

Description:
The isxdigit function tests c to determine if it is a hexadecimal digit ('A'-'Z', 'a'-'z', '0'-'9').

Return Value:
The isxdigit function returns a value of 1 if c is a hexadecimal digit and a value of 0 if it is not.

Attributes:
reentrant

See Also:
isalnum, isalpha, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_isxdigit (void)  {
  unsigned char i;
  char *p;

  for (i = 0; i < 128; i++)  {
    p = (isxdigit (i) ? "YES" : "NO");

    printf ("isxdigit (%c) %s\n", i, p);


labs

#include <math.h>
long labs (long val);    /* value to calc. abs. value for */

Description:
The labs function determines the absolute value of the long integer val.

Return Value:
The labs function returns the absolute value of val.

Attributes:
reentrant

See Also:
abs , cabs, fabs

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_labs (void)  {
  long x;
  long y;

  x = -12345L;

  y = labs (x);

  printf ("LABS(%ld) = %ld\n", x, y);


log / log517

#include <math.h>
float log (float val);   /* value to take natural logarithm of */

Description:
The log function calculates the natural logarithm for the floating-point number val. The natural logarithm uses the base e or 2.718282…

The log517 function is identical to log, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function, include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The log function returns the floating-point natural logarithm of val.

Attributes:
non-reentrant

See Also:
exp / exp517, log10 / log10517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_log (void)  {
  float x;
  float y;

  x = 2.71838;
  x *= x;

  y = log (x);                               /* y = 2 */

  printf ("LOG(%f) = %f\n", x, y);


log10 / log10517

#include <math.h>
float log10 (float val);   /* value to take common logarithm of */

Description:
The log10 function calculates the common logarithm for the floating-point number val. The common logarithm uses base 10.

The log10517 function is identical to log10, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function, include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The log10 function returns the floating-point common logarithm of val.

Attributes:
non-reentrant

See Also:
exp / exp517, log / log517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_log10 (void)  {
  float x;
  float y;

  x = 1000;

  y = log10 (x);                             /* y = 3 */

  printf ("LOG10(%f) = %f\n", x, y);


longjmp

#include <setjmp.h>
void longjmp (jmp_buf env,   /* environment to restore */
              int retval);   /* return value           */

Description:
The longjmp function restores the state which was previously stored in env by the setjmp function. The retval argument specifies the value to return from the setjmp function call.

The longjmp and setjmp functions can be used to execute a non-local goto and are usually utilized to pass control to an error recovery routine.

Local variables and function arguments are restored only if declared with the volatile attribute.

Return Value:
None.

Attributes:
reentrant

See Also:
setjmp

Example
#include <setjmp.h>
#include <stdio.h>                      /* for printf */

jmp_buf env;     /* jump environment (must be global) */
bit error_flag;

void trigger (void)  {
  .
  .
  .
  /* put processing code here */
  .
  .
  .
  if (error_flag != 0)  {
    longjmp (env, 1);           /* return 1 to setjmp */
  }
  .
  .
  .
}

void recover (void)  {
            /* put recovery code here */
}

void tst_longjmp (void)  {
  .
  .
  .
  if (setjmp (env) != 0)  {     /* setjmp returns a 0 */
    printf ("LONGJMP called\n");
    recover ();
  }
  else  {
    printf ("SETJMP called\n");

    error_flag = 1;                 /* force an error */

    trigger ();


_lrol_

#include <intrins.h>
unsigned long _lrol_ (unsigned long l,    /* 32-bit integer to rotate left */
                      unsigned char b);   /* bit positions to rotate       */

Description:
The _lrol_ routine rotates the bit pattern for the long integer l left b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _lrol_ routine returns the rotated value of l.

Attributes:
reentrant, intrinsic

See Also:
_cror_, _crol_, _irol_, _iror_, _lror_

Example
#include <intrins.h>

void tst_lrol (void)  {
  long a;
  long b;

  a = 0xA5A5A5A5;

  b = _lrol_(a,3);             /* b now is 0x2D2D2D2D */


_lror_

#include <intrins.h>
unsigned long _lror_ (unsigned long l,    /* 32-bit int to rotate right */
                      unsigned char b);   /* bit positions to rotate    */

Description:
The _lror_ routine rotates the bit pattern for the long integer l right b bits. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _lror_ routine returns the rotated value of l.

Attributes:
reentrant, intrinsic

See Also:
_cror_, _crol_, _irol_, _iror_, _lrol_

Example
#include <intrins.h>

void tst_lror (void)  {
  long a;
  long b;

  a = 0xA5A5A5A5;

  b = _lrol_(a,1);             /* b now is 0xD2D2D2D2 */


malloc

#include <stdlib.h>
void *malloc (unsigned int size);    /* block size to allocate */

Description:
The malloc function allocates a memory block from the memory pool of size bytes in length.

NOTE
Source code is provided for this routine in the LIB directory. You may modify the source to customize this function for your hardware environment.

Return Value:
The malloc function returns a pointer to the allocated block or a null pointer if there was not enough memory to satisfy the allocation request.

Attributes:
non-reentrant

See Also:
calloc, free, init_mempool, realloc

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_malloc (void)  {
  unsigned char xdata *p;

  p = malloc (1000);           /* allocate 1000 bytes */

  if (p == NULL)
    printf ("Not enough memory space\n");
    else
      printf ("Memory allocated\n");


memccpy

#include <string.h>
void *memccpy (void *dest,   /* destination buffer        */
               void *src,    /* source buffer             */
               char c,       /* character which ends copy */
               int len);     /* maximum bytes to copy     */

Description:
The memccpy function copies 0 or more characters from src to dest. Characters are copied until the character c is copied or until len bytes have been copied, whichever comes first.

Return Value:
The memccpy function returns a pointer to the byte in dest that follows the last character copied or a null pointer if the last character copied was c.

Attributes:
non-reentrant

See Also:
memchr, memcmp, memcpy, memmove, memset

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memccpy (void)  {
  static char src1 [100] = "Copy this string
                            to dst1";
  static char dst1 [100];

void *c;

  c = memccpy (dst1, src1, 'g', sizeof (dst1));

  if (c == NULL)
    printf ("'g' was not found in the src
              buffer\n");
    else
      printf ("characters copied up to 'g'\n");


memchr

#include <string.h>
void *memchr (void *buf,  /* buffer to search      */
              char c,     /* byte to find          */
              int len);   /* maximum buffer length */

Description:
The memchr function scans buf for the character c in the first len bytes of the buffer.

Return Value:
The memchr function returns a pointer to the character c in buf or a null pointer if the character was not found.

Attributes:
reentrant

See Also:
memccpy, memcmp, memcpy, memmove, memset

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memchr (void)  {
  static char src1 [100] =
  "Search this string from the start";

  void *c;

  c = memchr (src1, 'g', sizeof (src1));

  if (c == NULL)
    printf ("'g' was not found in the buffer\n");
  else
    printf ("found 'g' in the buffer\n");


memcmp

#include <string.h>
char memcmp (void *buf1,   /* first buffer             */
             void *buf2,   /* second buffer            */
             int len);     /* maximum bytes to compare */

Description:
The memcmp function compares two buffers buf1 and buf2 for len bytes and returns a value indicating their relationship as follows:

Value | Meaning
< 0 | buf1 less than buf2
= 0 | but1 equal to buf2
> 0 | buf1 greater than buf2

Return Value:
The memcmp function returns a positive, negative, or zero value indicating the relationship of buf1 and buf2.

Attributes:
reentrant

See Also:
memccpy, memchr, memcpy, memmove, memset

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memcmp (void)  {
  static char hexchars  [] = "0123456789ABCDEF";
  static char hexchars2 [] = "0123456789abcdef";

  char i;

  i = memcmp (hexchars, hexchars2, 16);

  if (i < 0)
    printf ("hexchars < hexchars2\n");

  else if (i > 0)
    printf ("hexchars > hexchars2\n");

  else
    printf ("hexchars == hexchars2\n");


memcpy

#include <string.h>
void *memcpy (void *dest,  /* destination buffer    */
              void *src,   /* source buffer         */
              int len);    /* maximum bytes to copy */

Description:
The memcpy function copies len bytes from src to dest. If these memory buffers overlap, the memcpy function cannot guarantee that bytes in src are copied to dest before being overwritten. If these buffers do overlap, use the memmove function.

Return Value:
The memcpy function returns dest.

Attributes:
reentrant

See Also:
memccpy, memchr, memcmp, memmove, memset

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memcpy (void)  {
  static char src1 [100] =
  "Copy this string to dst1";

  static char dst1 [100];

  char *p;

  p = memcpy (dst1, src1, sizeof (dst1));

  printf ("dst = \"%s\"\n", p);


memmove

#include <string.h>
void *memmove (void *dest,   /* destination buffer    */
               void *src,    /* source buffer         */
               int len);     /* maximum bytes to move */

Description:
The memmove function copies len bytes from src to dest. If these memory buffers overlap, the memmove function ensures that bytes in src are copied to dest before being overwritten.

Return Value:
The memmove function returns dest.

Attributes:
reentrant

See Also:
memccpy, memchr, memcmp, memcpy, memset

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memmove (void)  {
  static char buf [] = "This is line 1  "
                       "This is line 2  "
                       "This is line 3  ";

  printf ("buf before = %s\n", buf);

  memmove (&buf [0], &buf [16], 32);

  printf ("buf after  = %s\n", buf);


memset

#include <string.h>
void *memset (void *buf,    /* buffer to initialize */
              char c,       /* byte value to set    */
              int len);     /* buffer length        */

Description:
The memset function sets the first len bytes in buf to c.

Return Value:
The memset function returns dest.

Attributes:
reentrant

See Also:
memccpy, memchr, memcmp, memcpy, memmove

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_memset (void)  {
  char buf [10];

  memset (buf, '\0', sizeof (buf));
                  /* fill buffer with null characters */


modf

#include <math.h>
float modf (float val,    /* value to calculate modulo for */
            float *ip);   /* integer portion of modulo     */

Description:
The modf function splits the floating-point number val into integer and fractional components. The fractional part of val is returned as a signed floating-point number. The integer part is stored as a floating-point number at ip.

Return Value:
The modf function returns the signed fractional part of val.

Attributes:
non-reentrant

See Also:
-

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_modf (void)  {
  float x;
  float int_part, frc_part;

  x = 123.456;

  frc_part = modf (x, &int_part);

  printf ("%f = %f + %f\n", x, int_part,frc_part);


_nop_

#include <intrins.h>
void _nop_ (void);

Description:
The _nop_ routine inserts an 8051 NOP instruction into the program. This routine can be used to pause for 1 CPU cycle. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
None.

Attributes:
reentrant, intrinsic

See Also:
-

Example
#include <intrins.h>
#include <stdio.h>                      /* for printf */

void tst_nop (void)  {

  P1 = 0xFF;

  _nop_ ();                     /* delay for hardware */
  _nop_ ();
  _nop_ ();

  P1 = 0x00;


offsetof

#include <stddef.h>
int offsetof (structure,   /* structure to use         */
              member);     /* member to get offset for */

Description:
The offsetof macro calculates the offset of the member structure element from the beginning of the structure. The structure argument must specify the name of a structure. The member argument must specify the name of a member of the structure.

Return Value:
The offsetof macro returns the offset, in bytes, of the member element from the beginning of struct structure.

Attributes:
-

See also:
-

Example
#include <stddef.h>

struct index_st
  {
  unsigned char type;
  unsigned long num;
  unsigned ing len;
  };

typedef struct index_st index_t;

void main (void)
{
int x, y;

x = offsetof (struct index_st, len);  /* x = 5 */
y = offsetof (index_t, num);          /* x = 1 */


pow

#include <math.h>
float pow (float x,     /* value to use for base     */
           float y);    /* value to use for exponent */

Description:
The pow function calculates x raised to the yth power.

Return Value:
The pow function returns the value xy. If x 0 and y = 0, pow returns a value of 1. If x = 0 and y ≤ 0, pow returns NaN. If x < 0 and y is not an integer, pow returns NaN.

Attributes:
non-reentrant

See Also:
sqrt / sqrt517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_pow (void)  {
  float base;
  float power;
  float y;

  base  = 2.0;
  power = 8.0;

  y = pow (base, power);                   /* y = 256 */

  printf ("%f ^ %f = %f\n", base, power, y);


printf / printf517

#include <stdio.h>
int printf (const char *fmtstr   /* format string        */
            [, arguments]…);     /* additional arguments */

Description:
The printf function formats a series of strings and numeric values and builds a string to write to the output stream using the putchar function. The fmtstr argument is a format string and may be composed of characters, escape sequences, and format specifications.

Ordinary characters and escape sequences are copied to the stream in the order in which they are interpreted. Format specifications always begin with a percent sign ('%') and require additional arguments to be included in the function call.

The format string is read from left to right. The first format specification encountered references the first argument after fmtstr and converts and outputs it using the format specification. The second format specification accesses the second argument after fmtstr, and so on. If there are more arguments than format specifications, the extra arguments are ignored. Results are unpredictable if there are not enough arguments for the format specifications.

Format specifications have the following format:

% [flags ] [ width ] [. precision ] [{b | B | l | L} ] type

Each field in the format specification can be a single character or a number which specifies a particular format option.

The type field is a single character that specifies whether the argument is interpreted as a character, string, number, or pointer, as shown in the following table.

Character | Argument Type | Output Format
d | int | Signed decimal number
u | unsigned int | Unsigned decimal number
o | unsigned int | Unsigned octal number
x | unsigned int | Unsigned hexadecimal number using "0123456789abcdef"
X | unsigned int | Unsigned hexadecimal number using "0123456789ABCEDF"
f | float | Floating-point number using the format [-]dddd.dddd
e | float | Floating-point number using the format [-]d.dddde[-]dd
E | float | Floating-point number using the format [-]d.ddddE[-]dd
g | float | Floating-point number using either e or f format, whichever is more compact for the specified value and precision
G | float | Identical to the g format except that (where applicable) E precedes the exponent instead of e
c | char | Single character
s | generic * | String with a terminating null character
p | generic * | Pointer using the format t:aaaa where t is the memory type the pointer references (c: code, i: data/idata, x: xdata, p: pdata) and aaaa is the hexadecimal address

The optional characters b or B and l or L may immediately precede the type character to respectively specify char or long versions of the integer types d, i, u, o, x, and X.

The flags field is a single character used to justify the output and to print +/- signs and blanks, decimal points, and octal and hexadecimal prefixes, as shown in the following table.

Flag | Meaning
- | Left justify the output in the specified field width.
+ | Prefix the output value with a + or - sign if the output is a signed type.
blank (' ') | Prefix the output value with a blank if it is a signed positive value. Otherwise, no blank is prefixed.
# | Prefixes a non-zero output value with 0, 0x, or 0X when used with o, x, and X field types, respectively. When used with the e, E, f, g, and G field types, the # flag forces the output value to include a decimal point. The # flag is ignored in all other cases.
* | Ignore format specifier.

The width field is a non-negative number that specifies the minimum number of characters printed. If the number of characters in the output value is less than width, blanks are added on the left or right (when the - flag is specified) to pad to the minimum width. If width is prefixed with a '0', zeros are padded instead of blanks. The width field never truncates a field. If the length of the output value exceeds the specified width, all characters are output.

The width field may be an asterisk ('*'), in which case an int argument from the argument list provides the width value. Specifying a 'b' in front of the asterisk specifies that the argument used is an unsigned char.

The precision field is a non-negative number that specifies the number of characters to print, the number of significant digits, or the number of decimal places. The precision field can cause truncation or rounding of the output value in the case of a floating-point number as specified in the following table.

Type | Meaning of Precision Field
d, u, o, x, X | The precision field is where you specify the minimum number of digits that are included in the output value. Digits are not truncated if the number of digits in the argument exceeds that defined in the precision field. If the number of digits in the argument is less than the precision field, the output value is padded on the left with zeros.
f | The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.
e, E | The precision field is where you specify the number of digits to the right of the decimal point. The last digit is rounded.
g, G | The precision field is where you specify the maximum number of significant digits in the output value.
c, p | The precision field has no effect on these field types.
s | The precision field is where you specify the maximum number of characters in the output value. Excess characters are not output.

The precision field may be an asterisk ('*'), in which case an int argument from the argument list provides the value for the precision. Specifying a 'b' in front of the asterisk specifies that the argument used is an unsigned char.

The printf517 function is identical to printf, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function, include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

NOTE
This function is implementation-specific and is based on the operation of the putchar function. This function, as provided in the standard library, writes characters using the serial port of the 8051. Custom functions may use other I/O devices.

You must ensure that the argument type matches that of the format specification. You can use type casts to ensure that the proper type is passed to printf.

The total number of bytes that may be passed to printf is limited due to the memory restrictions imposed by the 8051. A maximum of 15 bytes may be passed in small model or compact model. A maximum of 40 bytes may be passed in large model.

Return Value:
The printf function returns the number of characters actually written to the output stream.

Attributes:
non-reentrant

See Also:
gets, puts, scanf, sprintf / sprintf517, sscanf / sscanf517, vprintf, vsprintf

Example
#include <stdio.h>

void tst_printf (void)  {
  char a;
  int  b;
  long c;
  unsigned char x;
  unsigned int  y;
  unsigned long z;
  float f,g;
  char buf [] = "Test String";
  char *p = buf;

  a = 1;
  b = 12365;
  c = 0x7FFFFFFF;
  x = 'A';
  y = 54321;
  z = 0x4A6F6E00;
  f = 10.0;
  g = 22.95;

  printf ("char %bd  int %d  long %ld\n",a,b,c);
  printf ("Uchar %bu Uint %u Ulong %lu\n",x,y,z);
  printf ("xchar %bx xint %x xlong %lx\n",x,y,z);
  printf ("String %s is at address %p\n",buf,p);
  printf ("%f != %g\n", f, g);
  printf ("%*f != %*g\n", 8, f, 8, g);


putchar

#include <stdio.h>
char putchar (char c);   /* character to output */

Description:
The putchar function transmits the character c using the 8051 serial port.

NOTE
This routine is implementation-specific and its function may deviate from that described above. Source is included for the _getkey and putchar functions which may be modified to provide character level I/O for any hardware device.

Return Value:
The putchar routine returns the character output, c.

Attributes:
non-reentrant

See Also:
getchar, _getkey, ungetchar

Example
#include <stdio.h>

void tst_putchar (void)  {
  unsigned char i;

  for (i = 0x20; i < 0x7F; i++)
    putchar (i);


puts

#include <stdio.h>
int puts (const char *string);   /* string to output */

Description:
The puts function writes string followed by a newline character ('\n') to the output stream using the putchar function.

NOTE
This function is implementation-specific and is based on the operation of the putchar function. This function, as provided in the standard library, writes characters using the serial port of the 8051. Custom functions may use other I/O devices.

Return Value:
The puts function returns EOF if an error occurred and a value of 0 if no errors were encountered.

Attributes:
reentrant

See Also:
gets, printf / printf517, scanf

Example
#include <stdio.h>

void tst_puts (void)  {

  puts ("Line #1");
  puts ("Line #2");
  puts ("Line #3");


rand

#include <stdlib.h>
int rand (void);

Description:
The rand function generates a pseudo-random number between 0 and 32767.

Return Value:
The rand function returns a pseudo-random number.

Attributes:
reentrant

See Also:
srand

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_rand (void)  {
  int i;
  int r;

  for (i = 0; i < 10; i++)  {
    printf ("I = %d, RAND = %d\n", i, rand ());


realloc

#include <stdlib.h>
void *realloc (void xdata *p,        /* previously allocated block */
               unsigned int size);   /* new size for block         */

Description:
The realloc function changes the size of a previously allocated memory block. The p argument points to the allocated block and the size argument specifies the new size for the block. The contents of the existing block are copied to the new block. Any additional area in the new block, due to a larger block size, is not initialized.

NOTE
Source code is provided for this routine in the \c51\lib directory. You can modify the source to customize this function for your hardware environment.

Return Value:
The realloc function returns a pointer to the new block. If there is not enough memory in the memory pool to satisfy the memory request, a null pointer is returned and the original memory block is not affected.

Attributes:
non-reentrant

See Also:
calloc, free, init_mempool, malloc

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_realloc (void)  {
  void xdata *p;
  void xdata *new_p;

  p = malloc (100);
  if (p != NULL)  {
    new_p = realloc (p, 200);

    if (new_p != NULL)  p = new_p;
    else  printf ("Reallocation failed\n");


scanf

#include <stdio.h>
int scanf (const char *fmtstr   /* format string        */
           [, argument]…);      /* additional arguments */

Description:
The scanf function reads data using the getchar routine. Data input are stored in the locations specified by argument according to the format string fmtstr. Each argument must be a pointer to a variable that corresponds to the type defined in fmtstr which controls the interpretation of the input data. The fmtstr argument is composed of one or more whitespace characters, non-whitespace characters, and format specifications as defined below.

The scanf517 function is identical to scanf, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

  • Whitespace characters, blank (' '), tab ('\t'), or newline ('\n'), causes scanf to skip whitespace characters in the input stream. A single whitespace character in the format string matches 0 or more whitespace characters in the input stream.
  • Non-whitespace characters, with the exception of the percent sign ('%'), cause scanf to read but not store a matching character from the input stream. The scanf function terminates if the next character in the input stream does not match the specified non-whitespace character.
  • Format specifications begin with a percent sign ('%') and cause scanf to read and convert characters from the input stream to the specified type values. The converted value is stored to an argument in the parameter list. Characters following a percent sign that are not recognized as a format specification are treated as an ordinary character. For example, %% matches a single percent sign in the input stream.

The format string is read from left to right. Characters that are not part of the format specifications must match characters in the input stream. These characters are read from the input stream but are discarded and not stored. If a character in the input stream conflicts with the format string, scanf terminates. Any conflicting characters remain in the input stream.

The first format specification encountered in the format string references the first argument after fmtstr and converts input characters and stores the value using the format specification. The second format specification accesses the second argument after fmtstr, and so on. If there are more arguments than format specifications, the extra arguments are ignored. Results are unpredictable if there are not enough arguments for the format specifications.

Values in the input stream are called input fields and are delimited by whitespace characters. When converting input fields, scanf ends a conversion for an argument when a whitespace character is encountered. Additionally, any unrecognized character for the current format specification ends a field conversion.

Format specifications have the following format:

% [* ] [ width ] [ {b | h | l} ] type

Each field in the format specification can be a single character or a number which specifies a particular format option.

The type field is where a single character specifies whether input characters are interpreted as a character, string, or number. This field can be any one of the characters in the following table.

Character | Argument Type | Input Format
d | int * | Signed decimal number
i | int * | Signed decimal, hexadecimal, or octal integer
u | unsigned int * | Unsigned decimal number
o | unsigned int * | Unsigned octal number
x | unsigned int * | Unsigned hex number
e | float * | Floating-point number
f | float * | Floating-point number
g | float * | Floating-point number
c | char * | A single character
s | char * | A string of characters terminated by whitespace

An asterisk (*) as the first character of a format specification causes the input field to be scanned but not stored. The asterisk suppresses assignment of the format specification.

The width field is a non-negative number that specifies the maximum number of characters read from the input stream. No more than width characters are read from the input stream and converted for the corresponding argument. However, fewer than width characters may be read if a whitespace character or an unrecognized character is encountered first.

The optional characters b, h, and l may immediately precede the type character to respectively specify char, short, or long versions of the integer types d, i, u, o, and x.

NOTE
This function is implementation-specific and is based on the operation of the _getkey and/or putchar functions. These functions, as provided in the standard library, read and write characters using the serial port of the 8051. Custom functions may use other I/O devices.

The total number of bytes that may be passed to scanf is limited due to the memory restrictions imposed by the 8051. A maximum of 15 bytes may be passed in small model or compact model. A maximum of 40 bytes may be passed in large model.

Return Value:
The scanf function returns the number of input fields that were successfully converted. An EOF is returned if an error is encountered.

Attributes:
non-reentrant

See Also:
gets, printf / printf517, puts, sprintf / sprintf517, sscanf / sscanf517, vprintf, vsprintf

Example
#include <stdio.h>

void tst_scanf (void)  {
  char a;
  int  b;
  long c;

  unsigned char x;
  unsigned int  y;
  unsigned long z;

  float f,g;

  char d, buf [10];

  int argsread;

  printf ("Enter a signed byte, int, and long\n");
  argsread = scanf ("%bd %d %ld", &a, &b, &c);
  printf ("%d arguments read\n", argsread);

  printf ("Enter an unsigned byte, int, and long\n");
  argsread = scanf ("%bu %u %lu", &x, &y, &z);
  printf ("%d arguments read\n", argsread);

  printf ("Enter a character and a string\n");
  argsread = scanf ("%c %9s", &d, buf);
  printf ("%d arguments read\n", argsread);

  printf ("Enter two floating-point numbers\n");
  argsread = scanf ("%f %f", &f, &g);
  printf ("%d arguments read\n", argsread);


setjmp

#include <setjmp.h>
int setjmp (jmp_buf env);    /* current environment */

Description:
The setjmp function saves the current state of the CPU in env. The state can be restored by a subsequent call to the longjmp function. When used together, the setjmp and longjmp functions provide you with a way to execute a non-local goto.

A call to the setjmp function saves the current instruction address as well as other CPU registers. A subsequent call to the longjmp function restores the instruction pointer and registers, and execution resumes at the point just after the setjmp call.

Local variables and function arguments are restored only if declared with the volatile attribute.

Return Value:
The setjmp function returns a value of 0 when the current state of the CPU has been copied to env. A non-zero value indicates that the longjmp function was executed to return to the setjmp function call. In such a case, the return value is the value passed to the longjmp function.

Attributes:
reentrant

See Also:
longjmp

Example:
See longjmp


sin / sin517

#include <math.h>
float sin (float x);   /* value to calculate sine for */

Description:
The sin function calculates the sine of the floating-point value x. The value of x must be in the -65535 to +65535 range or an NaN error value is generated.

The sin517 function is identical to sin, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The sin function returns the sine of x.

Attributes:
non-reentrant

See Also:
cos / cos517, tan / tan517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_sin (void)  {
  float x;
  float y;

  for (x = 0; x < (2 * 3.1415); x += 0.1)  {
    y = sin (x);

    printf ("SIN(%f) = %f\n", x, y);


sinh

#include <math.h>
float sinh (float val);   /* value to calc hyperbolic sine for */

Description:
The sinh function calculates the hyperbolic sine of the floating-point value x. The value of x must be in the -65535 to +65535 range or an NaN error value is generated.

Return Value:
The sinh function returns the hyperbolic sine of x.

Attributes:
non-reentrant

See Also:
cosh, tanh

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_sinh (void)  {
  float x;
  float y;

  for (x = 0; x < (2 * 3.1415); x += 0.1)  {
    y = sinh (x);
    printf ("SINH(%f) = %f\n", x, y);


sprintf / sprintf517

#include <stdio.h>
int sprintf (char *buffer,         /* storage buffer       */
             const char *fmtstr,   /* format string        */
             [, argument]…);       /* additional arguments */

Description:

The sprintf function formats a series of strings and numeric values and stores the resulting string in buffer. The fmtstr argument is a format string and has the same requirements as specified for the printf function.

The sprintf517 function is identical to sprintf, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

NOTE
The total number of bytes that may be passed to sprintf is limited due to the memory restrictions imposed by the 8051. A maximum of 15 bytes may be passed in small model or compact model. A maximum of 40 bytes may be passed in large model.

Return Value:
The sprintf function returns the number of characters actually written to buffer.

Attributes:
non-reentrant

See Also:
gets, printf / printf517, puts, scanf, sscanf / sscanf517, vprintf, vsprintf

Example
#include <stdio.h>

void tst_sprintf (void)  {
  char buf [100];
  int n;

  int a,b;
  float pi;

  a = 123;
  b = 456;
  pi = 3.14159;

  n =  sprintf (buf,   "%f\n", 1.1);
  n += sprintf (buf+n, "%d\n", a);
  n += sprintf (buf+n, "%d %s %g", b, "---", pi);
  printf (buf);


sqrt / sqrt517

#include <math.h>
float sqrt (float x);   /* value to calculate square root of */

Description:
The sqrt function calculates the square root of x.

The sqrt517 function is identical to sqrt, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The sqrt function returns the positive square root of x.

Attributes:
non-reentrant

See Also:
exp / exp517, log / log517, pow

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_sqrt (void)  {
  float x;
  float y;

  x = 25.0;

  y = sqrt (x);                              /* y = 5 */

  printf ("SQRT(%f) = %f\n", x, y);


srand

#include <stdlib.h>
void srand (int seed);   /* random number generator seed */

Description:
The srand function sets the starting value seed used by the pseudo-random number generator in the rand function. The random number generator produces the same sequence of pseudo-random numbers for any given value of seed.

Return Value:
None.

Attributes:
non-reentrant

See Also:
rand

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_srand (void)  {
  int i;
  int r;

  srand (56);

  for (i = 0; i < 10; i++)  {
    printf ("I = %d, RAND = %d\n", i, rand ());


sscanf / sscanf517

#include <stdio.h>
int sscanf (char *buffer,        /* scanf input buffer    */
            const char *fmtstr   /* format string         */
            [, argument]…);      /* additional arguments  */

Description:
The sscanf function reads data from the string buffer. Data input are stored in the locations specified by argument according to the format string fmtstr. Each argument must be a pointer to a variable that corresponds to the type defined in fmtstr which controls the interpretation of the input data. The fmtstr argument is composed of one or more whitespace characters, non-whitespace characters, and format specifications, as defined in the scanf function description. Refer to scanf for a complete description of the formation string and additional arguments.

The sscanf517 function is identical to sscanf, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

NOTE
The total number of bytes that may be passed to sscanf is limited due to the memory restrictions imposed by the 8051. A maximum of 15 bytes may be passed in small model or compact model. A maximum of 40 bytes may be passed in large model.

Return Value:
The sscanf function returns the number of input fields that were successfully converted. An EOF is returned if an error is encountered.

Attributes:
non-reentrant

See Also:
gets, printf / printf517, puts, scanf, sprintf / sprintf517, vprintf, vsprintf

Example
#include <stdio.h>

void tst_sscanf (void)  {
  char a;
  int  b;
  long c;

  unsigned char x;
  unsigned int  y;
  unsigned long z;

  float f,g;

  char d, buf [10];

  int argsread;

  printf ("Reading a signed byte, int,and long\n");
  argsread = sscanf ("1 -234 567890", "%bd %d %ld", &a, &b, &c);
  printf ("%d arguments read\n", argsread);

  printf ("Reading an unsigned byte, int, and long\n");
  argsread = sscanf ("2 44 98765432", "%bu %u %lu", &x, &y, &z);
  printf ("%d arguments read\n", argsread);

  printf ("Reading a character and a string\n");
  argsread = sscanf ("a abcdefg", "%c %9s", &d, buf);
  printf ("%d arguments read\n", argsread);

  printf ("Reading two floating-point numbers\n");
  argsread = sscanf ("12.5 25.0", "%f %f", &f, &g);
  printf ("%d arguments read\n", argsread);


strcat

#include <string.h>
char *strcat (char *dest,   /* destination string */
              char *src);   /* source string      */

Description:
The strcat function concatenates or appends src to dest and terminates dest with a null character.

Return Value:
The strcat function returns dest.

Attributes:
non-reentrant

See Also:
strcpy, strlen, strncat, strncpy

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strcat (void)  {
  char buf [21];
  char s [] = "Test String";

  strcpy (buf, s);
  strcat (buf, " #2");

  printf ("new string is %s\n", buf);


strchr

#include <string.h>
char *strchr (const char *string,   /* string to search  */
              char c);              /* character to find */

Description:
The strchr function searches string for the first occurrence of c. The null character terminating string is included in the search.

Return Value:
The strchr function returns a pointer to the character c found in string or a null pointer if no matching character was found.

Attributes:
reentrant

See Also:
strcspn, strrpbrk, strpos, strrchr, strrpbrk, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strchr (void)  {
  char *s;
  char buf [] = "This is a test";

  s = strchr (buf, 't');

  if (s != NULL)
    printf ("found a 't' at %s\n", s);


strcmp

#include <string.h>
char strcmp (char *string1,    /* first string  */
             char *string2);   /* second string */

Description:
The strcmp function compares the contents of string1 and string2 and returns a value indicating their relationship.

Return Value:
The strcmp function returns the following values to indicate the relationship of string1 to string2:

Value | Meaning
< 0 | string1 less than string2
= 0 | string1 equal to string2
> 0 | string1 greater than string2

Attributes:
reentrant

See Also:
memcmp, strncmp

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strcmp (void)  {
  char buf1 [] = "Bill Smith";
  char buf2 [] = "Bill Smithy";
  char i;

  i = strcmp (buf1, buf2);

  if (i < 0)
    printf ("buf1 < buf2\n");

  else if (i > 0)
    printf ("buf1 > buf2\n");

  else
    printf ("buf1 == buf2\n");


strcpy

#include <string.h>
char *strcpy (char *dest,   /* destination string */
              char *src);   /* source string      */

Description:
The strcpy function copies src to dest and appends a null character to the end of dest.

Return Value:
The strcpy function returns dest.

Attributes:
reentrant

See Also:
strncat, strlen, strncat, strncpy

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strcpy (void)  {
  char buf [21];
  char s [] = "Test String";

  strcpy (buf, s);
  strcat (buf, " #2");

  printf ("new string is %s\n", buf);


strcspn

#include <string.h>
int strcspn (char *src,    /* source string      */
             char *set);   /* characters to find */

Description:
The strcspn function searches the src string for any of the characters in the set string.

Return Value:
The strcspn function returns the index of the first character located in src that matches a character in set. If the first character in src matches a character in set, a value of 0 is returned. If there are no matching characters in src, the length of the string is returned.

Attributes:
non-reentrant

See Also:
strchr, strpbrk, strpos, strrchr, strrpbrk, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strcspn (void)  {
  char buf [] = "13254.7980";
  int i;

  i = strcspn (buf, ".,");

  if (buf [i] != '\0')
    printf ("%c was found in %s\n", (char)
    buf [i], buf);


strlen

#include <string.h>
int strlen (char *src);   /* source string */

Description:
The strlen function calculates the length, in bytes, of src. This calculation does not include the null terminating character.

Return Value:

The strlen function returns the length of src.

Attributes:
reentrant

See Also:
strcat, strcpy, strncat, strncpy

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strlen (void)  {
  char buf [] = "Find the length of this string";
  int len;

  len = strlen (buf);    /* len = 30 */

  printf ("string length is %d\n", len);


strncat

#include <string.h>
char *strncat (char *dest,   /* destination string        */
               char *src,    /* source string             */
               int len);     /* max. chars to concatenate */

Description:
The strncat function appends at most len characters from src to dest and terminates dest with a null character. If src is shorter than len characters, src is copied up to and including the null terminating character.

Return Value:
The strncat function returns dest.

Attributes:
non-reentrant

See Also:
strcat, strcpy, strlen, strncpy

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strncat (void)  {
  char buf [21];

  strcpy  (buf, "test #");
  strncat (buf, "three", sizeof (buf) - strlen
           (buf));


strncmp

#include <string.h>
char strncmp (char *string1,    /* first string              */
              char *string2,    /* second string             */
              int len);         /* max characters to compare */

Description:
The strncmp function compares the first len bytes of string1 and string2 and returns a value indicating their relationship.

Return Value:
The strncmp function returns the following values to indicate the relationship of the first len bytes of string1 to string2:

Value | Meaning
< 0 | string1 less than string2
= 0 | string1 equal to string2
> 0 | string1 greater than string2

Attributes:
non-reentrant

See Also:
memcmp, strcmp

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strncmp (void)  {
  char str1 [] = "Wrodanahan     T.J.";
  char str2 [] = "Wrodanaugh     J.W.";

  char i;

  i = strncmp (str1, str2, 15);

  if (i < 0)       printf ("str1 < str2\n");
  else if (i > 0)  printf ("str1 > str2\n");
  else             printf ("str1 == str2\n");


strncpy

#include <string.h>
char *strncpy (char *dest,   /* destination string     */
               char *src,    /* source string          */
               int len);     /* max characters to copy */

Description:
The strncpy function copies at most len characters from src to dest. If src contains fewer characters than len, dest is padded out with null characters to len characters.

Return Value:
The strncpy function returns dest.

Attributes:
non-reentrant

See Also:
strcat, strcpy, strlen, strncat

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strncpy ( char *s)  {
  char buf [21];

  strncpy (buf, s, sizeof (buf));
  buf [sizeof (buf)] = '\0';


strpbrk

#include <string.h>
char *strpbrk (char *string,   /* string to search   */
               char *set);     /* characters to find */

Description:
The strpbrk function searches string for the first occurrence of any character from set. The null terminator is not included in the search.

Return Value:
The strpbrk function returns a pointer to the matching character in string. If string contains no characters from set, a null pointer is returned.

Attributes:
non-reentrant

See Also:
strchr, strcspn, strpos, strrchr, strrpbrk, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strpbrk (void)  {
  char vowels [] ="AEIOUaeiou";
  char text [] = "Seven years ago...";

  char *p;

  p = strpbrk (text, vowels);

  if (p == NULL)
    printf ("No vowels found in %s\n", text);

  else
    printf ("Found a vowel at %s\n", p);


strpos

#include <string.h>
int strpos (const char *string,   /* string to search  */
            char c);              /* character to find */

Description:
The strpos function searches string for the first occurrence of c. The null character terminating string is included in the search.

Return Value:
The strpos function returns the index of the character matching c in string or a value of -1 if no matching character was found. The index of the first character in string is 0.

Attributes:
reentrant

See Also:
strchr, strcspn, strpbrk, strrchr, strrpbrk, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strpos (void)  {
  char text [] = "Search this string for
  blanks";

  int i;

  i = strpos (text, ' ');

  if (i == -1)
    printf ("No spaces found in %s\n", text);

  else
    printf ("Found a space at offset %d\n", i);


strrchr

#include <string.h>
char *strrchr (const char *string,   /* string to search  */
               char c);              /* character to find */

Description:
The strrchr function searches string for the last occurrence of c. The null character terminating string is included in the search.

Return Value:
The strrchr function returns a pointer to the last character c found in string or a null pointer if no matching character was found.

Attributes:
reentrant

See Also:
strchr, strcspn, strpbrk, strpos, strrpbrk, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strrchr (void)  {
  char *s;
  char buf [] = "This is a test";

  s = strrchr (buf, 't');

  if (s != NULL)
    printf ("found the last 't' at %s\n", s);


strrpbrk

#include <string.h>
char *strrpbrk (char *string,   /* string to search   */
                char *set);     /* characters to find */

Description:
The strrpbrk function searches string for the last occurrence of any character from set. The null terminator is not included in the search.

Return Value:
The strrpbrk function returns a pointer to the last matching character in string. If string contains no characters from set, a null pointer is returned.

Attributes:
non-reentrant

See Also:
strchr, strcspn, strpbrk, strpos, strrchr, strrpos, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strrpbrk (void)  {
  char vowels [] ="AEIOUaeiou";
  char text [] = "American National Standards
                  Institute";

  char *p;

  p = strpbrk (text, vowels);

  if (p == NULL)
    printf ("No vowels found in %s\n", text);

  else
    printf ("Last vowel is at %s\n", p);


strrpos

#include <string.h>
int strrpos (const char *string,   /* string to search  */
             char c);              /* character to find */

Description:
The strrpos function searches string for the last occurrence of c. The null character terminating string is included in the search.

Return Value:
The strrpos function returns the index of the last character matching c in string or a value of -1 if no matching character was found. The index of the first character in string is 0.

Attributes:
reentrant

See Also:
strchr, strcspn, strpbrk, strpos, strrchr, strrpbrk, strspn

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strrpos (  char *s)  {

  int i;

  i = strpos (s, ' ');

  if (i == -1)
    printf ("No spaces found in %s\n", s);

  else
    printf ("Last space in %s is at offset %d\n",
             s, i);


strspn

#include <string.h>
int strspn (char *string,   /* string to search    */
            char *set);     /* characters to allow */

Description:
The strspn function searches the src string for characters not found in the set string.

Return Value:
The strspn function returns the index of the first character located in src that does not match a character in set. If the first character in src does not match a character in set, a value of 0 is returned. If all characters in src are found in set, the length of src is returned.

Attributes:
non-reentrant

See Also:
strchr, strcspn, strpbrk, strpos, strrchr, strrpbrk, strrpos

Example
#include <string.h>
#include <stdio.h>                      /* for printf */

void tst_strspn ( char *digit_str)  {
  char octd [] = "01234567";
  int i;

  i = strspn (digit_str, octd);

  if (digit_str [i] != '\0')
    printf ("%c is not an octal digit\n",
             digit_str [i]);


strtod/ strtod517

#include <stdlib.h>
unsigned long strtod (const char *string,   /* string to convert            */
                      char **ptr);          /* ptr to subsequent characters */

Description:
The strtod function converts string into a floating-point value. The input string is a sequence of characters that can be interpreted as a floating-point number. Whitespace characters at the beginning of string are skipped.

The strtod517 function is identical to atof, but uses the arithmetic unit of the Infineon 80C517 to provide faster execution. For using this function include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

The strtod function requires string to have the following format:
[{+ | -}] digits [. digits ][{e | E} [{+ | -} ] digits ]

where:

digitsmay be one or more decimal digits.

The value of ptr is set to point to the first character in string immediately following the converted part of the string. If ptr is NULL no value is assigned to ptr. If no conversion is possible, ptr is set to the value of string and the value 0 is returned by strtoul.

Return Value:
The strtod function returns the floating-point value that is produced by interpreting the characters in string as a number.

Attributes:
non-reentrant

See Also:
atof / atof517, atoi, atol, strtol, strtoul

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

void tst_strtod (void)  {
  float f;
  char s [] = "1.23";

  f = strtod (s, NULL);
  printf ("strtod(%s) = %f\n", s, f);


strtol

#include <stdlib.h>
long strtol (const char *string,   /* string to convert              */
             char **ptr,           /* ptr to subsequent characters   */
             unsigned char base);  /* number base for the conversion */

Description:
The strtol function converts string into a long value. The input string is a sequence of characters that can be interpreted as an integer number. Whitespace characters at the beginning of string are skipped. An optional sign may preceed the number.

The strtol function requires string to have the following format:
[whitespace] [{+ | -}] digits

where:
digitsmay be one or more decimal digits.

If base is zero, the number should have the format of a decimal-constant, octal-constant or hexadecimal-constant. The radix of the number is deduced from its format. If the value of base is between 2 and 36 the number must consist of nonzero sequnce of letters and digits representing an integer in the specified base. The letters a through z (or A through Z) represent the values 10 through 36, respectively. Only those letters representing values less than base are premitted. If base is 16 the number may begin with 0x or 0X, which is ignored.

The value of ptr is set to point to the first character in string immediately following the converted part of the string. If ptr is NULL no value is assigned to ptr. If no conversion is possible, ptr is set to the value of string and the value 0 is returned by strtol.

Return Value:
The strtol function returns the integer value that is produced by interpreting the characters in string as number. The value LONG_MIN or LONG_MAX is returned in case of overflow.

Attributes:
non-reentrant

See Also:
atof / atof517, atoi, atol, strtod/ strtod517, strtoul

Example
#include <stdlib.h>
#include <stdio.h>                         /* for printf */
char s [] = "12abCDe8";
void tst_strtol (void)  {
  long l;
  l = strtol (s, NULL, 16);
  printf ("strtol(%s) = %lx\n", s, l);
}
#include <reg51.h>
void main (void)  {
    SCON  = 0x50;            /* SCON: mode 1, 8-bit UART, enable rcvr */
    TMOD |= 0x20;               /* TMOD: timer 1, mode 2, 8-bit reload */
    TH1   = 221;                /* TH1:  reload value for 1200 baud @ 16MHz */
    TR1   = 1;                  /* TR1:  timer 1 run */
    TI    = 1;                  /* TI:   set TI to send first char of UART */
 tst_strtol ();


strtoul

#include <stdlib.h>
unsigned long strtoul (const char *string,    /* string to convert            */
                       char **ptr,            /* ptr to subsequent characters */
                       unsigned char base);   /* number base for conversion   */

Description:
The strtoul function converts string into an unsigned long value. The input string is a sequence of characters that can be interpreted as an integer number. Whitespace characters at the beginning of string are skipped. An optional sign may precede the number.

The strtoul function requires string to have the following format:
[ whitespace ] [{+ | -} ] digits

where:
digitsmay be one or more decimal digits.

If base is zero, the number should have the format of a decimal-constant, octal-constant or hexadecimal-constant. The radix of the number is deduced from its format. If the value of base is between 2 and 36 the number must consist of nonzero sequence of letters and digits representing an integer in the specified base. The letters a through z (or A through Z) represent the values 10 through 36, respectively. Only those letters representing values less than base are permitted. If base is 16 the number may begin with 0x or 0X, which is ignored.

The value of ptr is set to point to the first character in string immediately following the converted part of the string. If ptr is NULL no value is assigned to ptr. If no conversion is possible, ptr is set to the value of string and the value 0 is returned by strtoul.

Return Value:
The strtoul function returns the integer value that is produced by interpreting the characters in string as number. The value ULONG_MAX is returned in case of overflow.

Attributes:
non-reentrant

See Also:
atof / atof517, atoi, atol, strtod/ strtod517, strtol

Example
#include <stdlib.h>
#include <stdio.h>                      /* for printf */

char s [] = "12345AB";

void tst_strtoul (void)  {
  unsigned long ul;

  ul = strtoul (s, NULL, 16);
  printf ("strtoul(%s) = %lx\n", s, ul);


tan / tan517

#include <math.h>
float tan (float x);   /* value to calculate tangent of */

Description:
The tan function calculates the tangent of the floating-point value x. The value of x must be in the -65535 to +65535 range or an NaN error value is generated.

The tan517 function is identical to tan, but uses the arithmetic unit of the Siemens 80C517 to provide faster execution. When using this function, include the header file 80C517.H. Do not use this routine with a CPU that does not support this feature.

Return Value:
The tan function returns the tangent of x.

Attributes:
non-reentrant

See Also:
cos / cos517, sin / sin517

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_tan (void)  {
  float x, y, pi;

  pi = 3.14159;

  for (x = -(pi/4); x < (pi/4); x += 0.1)  {
    y = tan (x);
    printf ("TAN(%f) = %f\n", x, y);


tanh

#include <math.h>
float tanh (float x);   /* value to calc hyperbolic tangent for */

Description:
The tanh function calculates the hyperbolic tangent for the floating-point value x.

Return Value:
The tanh function returns the hyperbolic tangent of x.

Attributes:
non-reentrant

See Also:
cosh, sinh

Example
#include <math.h>
#include <stdio.h>                      /* for printf */

void tst_tanh (void)  {
  float x;
  float y;
  float pi;

  pi = 3.14159;

  for (x = -(pi/4); x < (pi/4); x += 0.1)  {
    y = tanh (x);
    printf ("TANH(%f) = %f\n", x, y);


_testbit_

#include <intrins.h>
bit _testbit_ (bit b);   /* bit to test and clear */

Description:
The _testbit_ routine produces a JBC instruction in the generated program code to simultaneously test the bit b and clear it to 0. This routine can be used only on directly addressable bit variables and is invalid on any type of expression. This routine is implemented as an intrinsic function. The code required is included in-line rather than being called.

Return Value:
The _testbit_ routine returns the value of b.

Attributes:
reentrant, intrinsic

See Also:
None.

Example
#include <intrins.h>
#include <stdio.h>                      /* for printf */

void tst_testbit (void){
  bit test_flag;

  if (_testbit_ (test_flag))
    printf ("Bit was set\n");

  else
    printf ("Bit was clear\n");


toascii

#include <ctype.h>
char toascii (char c);   /* character to convert */

Description:
The toascii macro converts c to a 7-bit ASCII character. This macro clears all but the lower 7 bits of c.

Return Value:
The toascii macro returns the 7-bit ASCII character for c.

Attributes:
reentrant

See Also:
toint

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_toascii ( char c)  {
  char k;

  k = toascii (c);

  printf ("%c is an ASCII character\n", k);


toint

#include <ctype.h>
char toint (char c);   /* digit to convert */

Description:
The toint function interprets c as a hexadecimal value. ASCII characters '0' through '9' generate values of 0 to 9. ASCII characters 'A' through 'F' and 'a' through 'f' generate values of 10 to 15.

Return Value:
The toint function returns the value of the ASCII hexadecimal character c.

Attributes:
reentrant

See Also:
toascii

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_toint (void)  {
  unsigned long l;
  char k;

  for (l = 0; isdigit (k = getchar ());
       l *= 10)  {

     l += toint (k);


tolower

#include <ctype.h>
char tolower (char c);   /* character to convert */

Description:
The tolower function converts c to a lowercase character. If c is not an alphabetic letter, the tolower function has no effect.

Return Value:
The tolower function returns the lowercase equivalent of c.

Attributes:
reentrant

See Also:
_tolower, toupper, _toupper

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_tolower (void)  {
  unsigned char i;

  for (i = 0x20; i < 0x7F; i++)  {
    printf ("tolower(%c) = %c\n", i, tolower(i));


_tolower

#include <ctype.h>
char _tolower (char c);   /* character to convert */

Description:
The _tolower macro is a version of tolower that can be used when c is known to be an uppercase character.

Return Value:
The _tolower macro returns a lowercase character.

Attributes:
reentrant

See Also:
tolower, toupper, _toupper

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst__tolower (  char k)  {

  if (isupper (k))   k = _tolower (k);


toupper

#include <ctype.h>
char toupper (char c);   /* character to convert */

Description:
The toupper function converts c to an uppercase character. If c is not an alphabetic letter, the toupper function has no effect.

Return Value:
The toupper function returns the uppercase equivalent of c.

Attributes:
reentrant

See Also:
tolower, _tolower, _toupper

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst_toupper (void)  {
  unsigned char i;

  for (i = 0x20; i < 0x7F; i++)  {
    printf ("toupper(%c) = %c\n", i, toupper(i));


_toupper

#include <ctype.h>
char _toupper (char c);   /* character to convert */

Description:
The _toupper macro is a version of toupper that can be used when c is known to be a lowercase character.

Return Value:
The _toupper macro returns an uppercase character.

Attributes:
reentrant

See Also:
tolower, _tolower, toupper

Example
#include <ctype.h>
#include <stdio.h>                      /* for printf */

void tst__toupper (  char k)  {
  if (islower (k))  k = _toupper (k);


ungetchar

#include <stdio.h>
char ungetchar (char c);   /* character to unget */

Description:
The ungetchar function stores the character c back into the input stream. Subsequent calls to getchar and other stream input functions return c. Only one character may be passed to unget between calls to getchar.

Return Value:
The ungetchar function returns the character c if successful. If ungetchar is called more than once between function calls that read from the input stream, EOF is returned indicating an error condition.

Attributes:
non-reentrant

See Also:
_getkey, putchar, ungetchar

Example
#include <stdio.h>

void tst_ungetchar (void)  {
  char k;

  while (isdigit (k = getchar ()))  {
          /* stay in the loop as long as k is a digit */
  }
  ungetchar (k);


va_arg

#include <stdarg.h>
type va_arg (argptr,   /* optional argument list */
             type);    /* type of next argument  */

Description:
The va_arg macro is used to extract subsequent arguments from a variable-length argument list referenced by argptr. The type argument specifies the data type of the argument to extract. This macro may be called only once for each argument and must be called in the order of the parameters in the argument list.

The first call to va_arg returns the first argument after the prevparm argument specified in the va_start macro. Subsequent calls to va_arg return the remaining arguments in succession.

Return Value:
The va_arg macro returns the value for the specified argument type.

Attributes:
reentrant

See Also:
va_end, va_start

Example
#include <stdarg.h>
#include <stdio.h>                      /* for printf */

int varfunc (char *buf, int id, ...)  {
  va_list tag;

  va_start (tag, id);

  if (id == 0)  {
    int arg1;
    char *arg2;
    long arg3;

    arg1 = va_arg (tag, int);
    arg2 = va_arg (tag, char *);
    arg3 = va_arg (tag, long);
  }
  else  {
    char *arg1;
    char *arg2;
    long arg3;

    arg1 = va_arg (tag, char *);
    arg2 = va_arg (tag, char *);
    arg3 = va_arg (tag, long);
  }
}

void caller (void)  {
  char tmp_buffer [10];

  varfunc (tmp_buffer, 0, 27, "Test Code", 100L);
  varfunc (tmp_buffer, 1, "Test", "Code", 348L);


va_end

#include <stdarg.h>
void va_end (argptr);   /* optional argument list */

Description:
The va_end macro is used to terminate use of the variable-length argument list pointer argptr that was initialized using the va_start macro.

Return Value:
None.

Attributes:
reentrant

See Also:
va_arg, va_start

Example:
See va_arg.


va_start

#include <stdarg.h>
void va_start (argptr,      /* optional argument list      */
               prevparm);   /* arg preceding optional args */

Description:
The va_start macro, when used in a function with a variable-length argument list, initializes argptr for subsequent use by the va_arg and va_end macros. The prevparm argument must be the name of the function argument immediately preceding the optional arguments specified by an ellipses (…). This function must be called to initialize a variable-length argument list pointer before any access using the va_arg macro is made.

Return Value:
None.

Attributes:
reentrant

See Also:
va_arg, va_end

Example:
See va_arg.


vprintf

#include <stdio.h>
void vprintf (const char * fmtstr,   /* pointer to format string */
              char * argptr);        /* pointer to argument list */

Description:
The vprintf function formats a series of strings and numeric values and builds a string to write to the output stream using the putchar function. The function is similar to the counterpart printf, but it accepts a pointer to a list of arguments instead of an argument list.

The fmtstr argument is a pointer to a format string and has the same form and function as the fmtstr argument for the printf function. Refer to printf / printf517 for a description of the format string. The argptr argument points to a list of arguments that are converted and output according to the corresponding format specifications in the format.

NOTE
This function is implementation-specific and is based on the operation of the putchar function. This function, as provided in the standard library, writes characters using the serial port of the 8051. Custom functions may use other I/O devices.

Return Value:
The vprintf function returns the number of characters actually written to the output stream.

Attributes:
non-reentrant

See Also:
gets, puts, printf / printf517, scanf, sprintf / sprintf517, sscanf / sscanf517, vsprintf

Example
#include <stdio.h>
#include <stdarg.h>

void error (char *fmt, ...)  {
  va_list arg_ptr;

  va_start (arg_ptr, fmt);           /* format string */
  vprintf (fmt, arg_ptr);
  va_end (arg_ptr);
}

void tst_vprintf (void)  {
  int i;
  i = 1000;
                     /* call error with one parameter */
  error ("Error: '%d' number too large\n", i);
              /* call error with just a format string */
  error ("Syntax Error\n");


vsprintf

#include <stdio.h>
void vsprintf (char *buffer,          /* pointer to storage buffer */
               const char * fmtstr,   /* pointer to format string  */
               char * argptr);        /* pointer to argument list  */

Description:
The vsprintf function formats a series of strings and numeric values and stores the string in buffer. The function is similar to the counterpart sprintf, but it accepts a pointer to a list of arguments instead of an argument list.

The fmtstr argument is a pointer to a format string and has the same form and function as the fmtstr argument for the printf function. Refer to printf / printf517 for a description of the format string. The argptr argument points to a list of arguments that are converted and output according the corresponding format specifications in the format.

Return Value:
The vsprintf function returns the number of characters actually written to the output stream.

Attributes:
non-reentrant

See Also:
gets, puts, printf / printf517, scanf, sprintf / sprintf517, sscanf / sscanf517, vprintf

Example
#include <stdio.h>
#include <stdarg.h>

xdata char etxt[30];                   /* text buffer */

void error (char *fmt, ...)  {
  va_list arg_ptr;

  va_start (arg_ptr, fmt);           /* format string */
  vsprintf (etxt, fmt, arg_ptr);
  va_end (arg_ptr);
}

void tst_vprintf (void)  {
  int i;
  i = 1000;

                     /* call error with one parameter */
  error ("Error: '%d' number too large\n", i);

              /* call error with just a format string */
  error ("Syntax Error\n");
}

The C51 compiler differs in only a few aspects from the ANSI C Standard. These differences can be grouped into compiler-related differences and library-related differences.


Compiler-related Differences

  • Wide Characters
    Wide 16-bit characters are not supported by C51. ANSI provides wide characters for future support of an international character set.
  • Recursive Function Calls
    Recursive function calls are not supported by default. Functions that are recursive must be declared using the reentrant function attribute. Reentrant functions can be called recursively because the local data and parameters are stored in a reentrant stack. In comparison, functions which are not declared using the reentrant attribute use static memory segments for the local data of the function. A recursive call to these functions overwrites the local data of the prior function call instance.


Library-related Differences

The ANSI C Standard Library includes a vast number of routines, most of which are included in C51. Many, however, are not applicable to an embedded application and are excluded from the C51 library.