ISO/ANSI C Standard

1 Standard output functions (printf family)

1.1 printf function

In Keil and IAR compilation platforms, users can directly use the printf function; in GCC, additional enabling RT_USING_POSIX_FSand RT_USING_POSIX_STDIOmacros are required to use the printf function.

1.2 Choosing between rt_kprintf and printf

If there is no special requirement, it is recommended to use the rt_kprintf function, because printf is provided by the compiler platform, and its space occupation and memory usage are unknown. The printf function occupies much more ROM than the rt_kprintf function.

Both the rt_kprintf function and the printf function are non-thread functions. When used by multiple threads at the same time, cross-printing may occur. This is normal because according to the requirements of the C standard, the printf function is non-thread-safe.

The native rt_kprintf function is optimized and occupies much less space than the printf function. However, the rt_kprintf function does not support floating-point output. Therefore:

1. If you need the rt_kprintf function to support floating-point output, you can install the rt_vsnprintf_full package .

2. If you need the rt_kprintf function to support thread-safe output, you can install the rt_kprintf_threadsafe package .

3. The above two packages can be installed and used at the same time to enable rt_kprintf to support thread safety and floating point type output capabilities.

1.3 Other string formatting output functions (such as snprintf, etc.)

Other string formatting output functions (such as snprintf, etc.) can be used directly.

It is strongly recommended that users use rt_snprintf and other RT-Thread functions instead of snprintf to reduce resource consumption. Especially under the GCC compilation chain, the snprintf function provided by Newlib (the default C library inside the GCC tool chain) is not thread-safe, and may cause a crash when multiple threads output floating-point numbers without protection (it is abnormal for the snprintf function to be non-thread-safe).

Similarly, native rt_snprintf and other functions do not support floating-point output. Users can install the rt_vsnprintf_full package to support floating-point output.

2 Memory related functions

The malloc, realloc, calloc, and free memory allocation functions can be used directly. They have been taken over by the rt_malloc, rt_calloc, rt_realloc, and rt_free functions. There is no difference between the two.

memcpy, memset and other memory operation related functions. It should be noted that it is recommended to use rt_memcpy and rt_memset instead of memcpy and memset. Although the rt_memxxx function is slower than the memory operation function of the C library, it is safer; unless you are very concerned about the copy speed, it is recommended to use the rt_memxxx function. If you are using a Cortex-M MCU, you can install the rt_memcpy_cm software package to accelerate the assembly of the rt_memcpy function. This software package is safe and efficient.

3 String related functions

String-related functions such as strlen are built-in functions of the compiler C library and can be used directly.

4 System functions

exit and abort functions, calling them is equivalent to deleting the current thread.

The system function can be used to execute some FinSH commands built into a C program.

5 Time function

All time functions specified by ANSI/ISO-C can be used, such as time, ctime, etc. Note: Some functions involving obtaining the current time require the RTC device to be enabled to work properly. If these functions are called without the RTC device enabled, a warning will be given in the serial terminal.

Supports time zone function. RT_LIBC_DEFAULT_TIMEZONEThe default time zone can be set through macro definition. The default time zone is UTC+8 Beijing time. During operation, you can also use tz_set(), tz_get(), tz_is_dst() functions to dynamically set or obtain time zone related information (need to include <sys/time.h> header file).

Notice:

1. Time zones are for people to see, not for machines to see. Therefore, the underlying driver should not use time with time zones, but should use Greenwich Mean Time, i.e., UTC+0. When and only when the time needs to be displayed to people, it is necessary to temporarily use a function with a time zone conversion function (such as ctime) to display the time. Otherwise, it is easy to cause time confusion.

   Note the difference between the following two groups of functions, which have the same functionality, the only difference being whether or not they take time zone issues into account:

   	Consider time zones	No time zone consideration
   Group 1	localtime	gmtime
   Group 2	mktime	timegm

2. Currently, time-related functions do not support automatic conversion to daylight saving time. Daylight saving time is not used in China, but mainly in Europe and the United States.

6 kservice.c

There is a file called kservice.c in the RT-Thread kernel. This file provides C library functions implemented by RT-Thread itself, such as rt_strlen, rt_strcpy, etc. The purpose of these functions is to make the RT-Thread kernel self-sustaining, that is, it can still run normally without relying on any C library. In addition, as mentioned above, some compiler built-in C library functions have some defects. The functions provided in the kservice.c file are safer and controllable. If you think that the functions provided in the kservice.c file are duplicated with the compiler built-in C library functions, you can remap most of the functions in kservice.c to the compiler built-in C library functions through configuration. For example: after turning on the option shown in the figure below, calling the rt_strlen function is actually equivalent to directly calling the strlen function of the compiler built-in C library.

kservice

7 Standard library C header files

7.1 Compatibility of different compilation platforms

To ensure compatibility across different compilers and tool chains, it is recommended that users apply the following code:

• Use sys/time.hinsteadtime.h

• Use sys/errno.hinsteaderrno.h

• Use sys/signal.hinsteadsignal.h

7.2 POSIX extension function declarations in standard library C header files

POSIX extends some function declarations based on the standard library C header file. For example, stdio.hthere is no getlinefunction in the standard C header file , which appears in stdio.hthe file in the POSIX.1-2008 standard. Therefore, if you use POSIX extended C library functions similar to the above (such as getline), you need to reference posix/stdio.hthe header file instead of stdio.hthe header file. The same applies to other C standard library header files, such as ctype.h, stdlib.hetc.

This is because the standard header files in the built-in C libraries of Keil, IAR, and WIN32 compilers only support the ISO-ANSI C standard and do not support POSIX extended function declarations. Therefore, the compiler balancing layer of RT-Thread uses this method to supplement the above three compilers, so that the upper-level code can run easily across compiler platforms.