legato.h

1 /**
2  * @page c_APIs lib Legato
3  *
4  * The Legato Application Framework provide a set of APIs to simplify common C programming tasks.
5  * @c lib @c Legato adds object oriented functions to simplify and enhance the safety and
6  * reliability of your systems.
7  *
8  * These APIs are available automatically to your applications by including @c legato.h into your
9  * code.
10  *
11  * It is also good practice to include @c interfaces.h. @c interfaces.h is a C header file that
12  * automatically includes all client and server interface definition that your client imports and
13  * exports. If you need to import or export any other API you will need to explicitly include
14  * @c interfaces.h into your C or C++ code.
15  *
16  @verbatim
17  #include "legato.h"
18  #include "interfaces.h"
19  @endverbatim
20  *
21  * | API Guide | API Reference | File Name | Description |
22  * | -----------------------------|-----------------------------| -------------------------| --------------------------------------------------------------------------------------------------------------------------|
23  * | @subpage c_args | @ref le_args.h | @c le_args.h | Provides the ability to add arguments from the command line |
24  * | @subpage c_atomFile | @ref le_atomFile.h | @c le_atomFile.h | Provides atomic file access mechanism that can be used to perform file operation (specially file write) in atomic fashion |
25  * | @subpage c_basics | @ref le_basics.h | @c le_basics.h | Provides error codes, portable integer types, and helpful macros that make things easier to use |
26  * | @subpage c_clock | @ref le_clock.h | @c le_clock.h | Gets/sets date and/or time values, and performs conversions between these values. |
27  * | @subpage c_crc | @ref le_crc.h | @c le_crc.h | Provides the ability to compute the CRC of a binary buffer |
28  * | @subpage c_dir | @ref le_dir.h | @c le_dir.h | Provides functions to control directories |
29  * | @subpage c_doublyLinkedList | @ref le_doublyLinkedList.h | @c le_doublyLinkedList.h | Provides a data structure that consists of data elements with links to the next node and previous nodes |
30  * | @subpage c_eventLoop | @ref le_eventLoop.h | @c le_eventLoop.h | Provides event loop functions to support the event-driven programming model |
31  * | @subpage c_fdMonitor | @ref le_fdMonitor.h | @c le_fdMonitor.h | Provides monitoring of file descriptors, reporting, and related events |
32  * | @subpage c_flock | @ref le_fileLock.h | @c le_fileLock.h | Provides file locking, a form of IPC used to synchronize multiple processes' access to common files |
33  * | @subpage c_fs | @ref le_fs.h | @c le_fs.h | Provides a way to access the file system across different platforms |
34  * | @subpage c_hashmap | @ref le_hashmap.h | @c le_hashmap.h | Provides creating, iterating and tracing functions for a hashmap |
35  * | @subpage c_hex | @ref le_hex.h | @c le_hex.h | Provides conversion between Hex and Binary strings |
36  * | @subpage c_json | @ref le_json.h | @c le_json.h | Provides fast parsing of a JSON data stream with very little memory required |
37  * | @subpage c_logging | @ref le_log.h | @c le_log.h | Provides a toolkit allowing code to be instrumented with error, warning, informational, and debugging messages |
38  * | @subpage c_memory | @ref le_mem.h | @c le_mem.h | Provides functions to create, allocate and release data from a memory pool |
39  * | @subpage c_messaging | @ref le_messaging.h | @c le_messaging.h | Provides support to low level messaging within Legato |
40  * | @subpage c_mutex | @ref le_mutex.h | @c le_mutex.h | Provides standard mutex functionality with added diagnostics capabilities |
41  * | @subpage c_pack | @ref le_pack.h | @c le_pack.h | Provides low-level pack/unpack functions to support the higher level IPC messaging system |
42  * | @subpage c_path | @ref le_path.h | @c le_path.h | Provides support for UTF-8 null-terminated strings and multi-character separators |
43  * | @subpage c_pathIter | @ref le_pathIter.h | @c le_pathIter.h | Iterate over paths, traverse the path node-by-node, or create and combine paths together |
44  * | @subpage c_rand | @ref le_rand.h | @c le_rand.h | Used for cryptographic purposes such as encryption keys, initialization vectors, etc. |
45  * | @subpage c_safeRef | @ref le_safeRef.h | @c le_safeRef.h | Protect from damaged or stale references being used by clients |
46  * | @subpage c_semaphore | @ref le_semaphore.h | @c le_semaphore.h | Provides standard semaphore functionality, but with added diagnostic capabilities |
47  * | @subpage c_signals | @ref le_signals.h | @c le_signals.h | Provides software interrupts for running processes or threads |
48  * | @subpage c_singlyLinkedList | @ref le_singlyLinkedList.h | @c le_singlyLinkedList.h | Provides a data structure consisting of a group of nodes linked together linearly |
49  * | @subpage c_test | @ref le_test.h | @c le_test.h | Provides macros that are used to simplify unit testing |
50  * | @subpage c_threading | @ref le_thread.h | @c le_thread.h | Provides controls for creating, ending and joining threads |
51  * | @subpage c_timer | @ref le_timer.h | @c le_timer.h | Provides functions for managing and using timers |
52  * | @subpage c_tty | @ref le_tty.h | @c le_tty.h | Provides routines to configure serial ports |
53  * | @subpage c_utf8 | @ref le_utf8.h | @c le_utf8.h | Provides safe and easy to use string handling functions for null-terminated strings with UTF-8 encoding |
54  *
55  * @section cApiOverview Overview
56  * Here is some background info on Legato's C Language APIs.
57  *
58  * @subsection cApiOverview_ood Object-Oriented Design
59  *
60  * The Legato framework is constructed in an object-oriented manner.
61  *
62  * The C programming language was created before object-oriented programming was
63  * popular so it doesn't have native support for OOP features like inheritance, private object
64  * members, member functions, and overloading. But object-oriented designs can still be
65  * implemented in C.
66  *
67  * In the Legato C APIs, classes are hidden behind opaque "reference" data types.
68  * You can get references to objects created behind the scenes in Legato, but
69  * you can never see the structure of those objects. The implementation is hidden from view.
70  * Access to object properties is made available through accessor functions.
71  *
72  * @subsection cApiOverview_ot Opaque Types
73  *
74  * The basic "opaque data type" offered by the C programming language is the "void pointer"
75  * <c>(void *)</c>.
76  * The idea is that a pointer to an object of type @a T can be cast to point to a <c>void</c> type
77  * before being passed outside of the module that implements @a T.
78  *
79  * This makes it impossible for anyone outside of the module that implements @a T to
80  * dereference the pointer or access anything about the implementation of @a T. This way,
81  * the module that implements @a T is free to change the implementation of @a T in any
82  * way needed without worrying about breaking code outside of that module.
83  *
84  * The problem with the void pointer type is that it throws away type information. At compile time,
85  * this makes it impossible to detect that a variable with opaque type @a T
86  * has been passed into a function with some other pointer type @a P.
87  *
88  * To overcome this, Legato uses "incomplete types" to implement its opaque types. For example,
89  * there are declarations similar to the following in Legato C API header files:
90  *
91  * @code
92  * // Declare a reference type for referring to Foo objects.
93  * typedef struct le_foo* le_foo_Ref_t;
94  * @endcode
95  *
96  * But "struct le_foo" would @a not be defined in the API header or @a anywhere outside of the
97  * hypothetical "Foo" API's implementation files. This makes "struct le_foo" an "incomplete type"
98  * for all code outside of the Foo API implementation files. Incomplete types can't be used
99  * because the compiler doesn't have enough information about them to generate any code
100  * that uses them. But @a pointers to incomplete types @a can be passed around because the compiler
101  * always knows the pointer size. The compiler knows that one incomplete type
102  * is @a not necessarily interchangeable with another, and it won't allow a pointer to
103  * an incomplete type to be used where a pointer to another non-void type is expected.
104  *
105  * @subsection cApiOverview_handlersEvents Handlers and Event-Driven Programs
106  *
107  * "Handler" is an alias for "callback function". Many APIs in the Legato world
108  * use callback functions to notify their clients of asynchronous events. For example, to
109  * register a function called "SigTermHandler" for notification of receipt of a TERM signal,
110  *
111  * @code
112  *
113  * le_sig_SetEventHandler(SIGTERM, SigTermHandler);
114  *
115  * @endcode
116  *
117  * Instead of using "CallbackFunction", "CallbackFunc", or some abbreviation like "CbFn"
118  * (Cub fun? Cubs fan? What?) that is difficult to read and/or remember, "Handler" is used.
119  *
120  * The term "handler" also fits with the event-driven programming style that is favoured in
121  * the Legato world. These callback functions are essentially event handler functions.
122  * That is, the function is called when an event occurs to "handle" that event.
123  *
124  * <HR>
125  *
126  * Copyright (C) Sierra Wireless Inc.
127  */
128 
129 //--------------------------------------------------------------------------------------------------
130 /**
131  * @file legato.h
132  *
133  * This file includes all the commonly-used Legato API header files.
134  * It's provided as a convenience to avoid including
135  * dozens of header files in every source file.
136  *
137  * Copyright (C) Sierra Wireless Inc.
138  */
139 //--------------------------------------------------------------------------------------------------
140 
141 #ifndef LEGATO_H_INCLUDE_GUARD
142 #define LEGATO_H_INCLUDE_GUARD
143 
144 #if defined(__cplusplus) && !defined(__STDC_LIMIT_MACROS)
145 // stdint.h from before C++11 only defines MAX and MIN macros if __STDC_LIMIT_MACROS is defined
146 #define __STDC_LIMIT_MACROS
147 #endif
148 
149 #include "le_config.h"
150 
151 #if LE_CONFIG_LINUX
152 # include "linux/legato.h"
153 #elif LE_CONFIG_CUSTOM_OS
154 # include "fa.h"
155 #else
156 # error "Unsupported OS type"
157 #endif
158 
159 #include <assert.h>
160 #include <ctype.h>
161 #include <errno.h>
162 #include <inttypes.h>
163 #include <limits.h>
164 #include <math.h>
165 #include <signal.h>
166 #include <stdarg.h>
167 #include <stdbool.h>
168 #include <stddef.h>
169 #include <stdint.h>
170 #include <stdio.h>
171 #include <stdlib.h>
172 #include <string.h>
173 #include <time.h>
174 
175 #ifdef __cplusplus
176 extern "C" {
177 #endif
178 
179 #include "le_basics.h"
180 #include "le_apiFeatures.h"
181 
182 #include "le_doublyLinkedList.h"
183 #include "le_singlyLinkedList.h"
184 #include "le_utf8.h"
185 #include "le_backtrace.h"
186 #include "le_log.h"
187 #include "le_mem.h"
188 #include "le_mutex.h"
189 #include "le_clock.h"
190 #include "le_cdata.h"
191 #include "le_semaphore.h"
192 #include "le_hashmap.h"
193 #include "le_redBlackTree.h"
194 #include "le_safeRef.h"
195 #include "le_thread.h"
196 #include "le_eventLoop.h"
197 #include "le_fdMonitor.h"
198 #include "le_signals.h"
199 #include "le_args.h"
200 #include "le_timer.h"
201 #include "le_messaging.h"
202 #include "le_test.h"
203 #include "le_pack.h"
204 #include "le_path.h"
205 #include "le_pathIter.h"
206 #include "le_hex.h"
207 #include "le_dir.h"
208 #include "le_fileLock.h"
209 #include "le_json.h"
210 #include "le_tty.h"
211 #include "le_atomFile.h"
212 #include "le_crc.h"
213 #include "le_fs.h"
214 #include "le_rand.h"
215 #include "le_fd.h"
216 #include "le_base64.h"
217 #include "le_process.h"
218 
219 #ifdef __cplusplus
220 }
221 #endif
222 
223 #endif // LEGATO_H_INCLUDE_GUARD