legato.h

Go to the documentation of this file.
1 /**
2  * @page c_APIs C Runtime Library
3  *
4  * This section contains detailed info about Legato's C Language library used for low-level routines like
5  * commonly used data structures and OS services APIs.
6  *
7  * <HR>
8  *
9  * The C APIs' @ref cApiOverview has high-level info.
10  *
11  * <HR>
12  *
13  * @subpage c_le_build_cfg <br>
14  * @subpage c_basics <br>
15  * @subpage c_args <br>
16  * @subpage c_atomFile <br>
17  * @subpage c_crc <br>
18  * @subpage c_dir <br>
19  * @subpage c_doublyLinkedList <br>
20  * @subpage c_memory <br>
21  * @subpage c_eventLoop <br>
22  * @subpage c_fdMonitor <br>
23  * @subpage c_flock <br>
24  * @subpage c_fs <br>
25  * @subpage c_hashmap <br>
26  * @subpage c_hex <br>
27  * @subpage c_json <br>
28  * @subpage c_logging <br>
29  * @subpage c_messaging <br>
30  * @subpage c_mutex <br>
31  * @subpage c_pack <br>
32  * @subpage c_path <br>
33  * @subpage c_pathIter <br>
34  * @subpage c_print <br>
35  * @subpage c_rand <br>
36  * @subpage c_safeRef <br>
37  * @subpage c_semaphore <br>
38  * @subpage c_signals <br>
39  * @subpage c_singlyLinkedList <br>
40  * @subpage c_clock <br>
41  * @subpage c_threading <br>
42  * @subpage c_timer <br>
43  * @subpage c_test <br>
44  * @subpage c_utf8 <br>
45  * @subpage c_tty
46  *
47  * @section cApiOverview Overview
48  * Here is some background info on Legato's C Language APIs.
49  *
50  * @subsection Object-Oriented Design
51  *
52  * The Legato framework is constructed in an object-oriented manner.
53  *
54  * The C programming language was created before object-oriented programming was
55  * popular so it doesn't have native support for OOP features like inheritance, private object
56  * members, member functions, and overloading. But object-oriented designs can still be
57  * implemented in C.
58  *
59  * In the Legato C APIs, classes are hidden behind opaque "reference" data types.
60  * You can get references to objects created behind the scenes in Legato, but
61  * you can never see the structure of those objects. The implementation is hidden from view.
62  * Access to object properties is made available through accessor functions.
63  *
64  * @subsection Opaque Types
65  *
66  * The basic "opaque data type" offered by the C programming language is the "void pointer"
67  * <c>(void *)</c>.
68  * The idea is that a pointer to an object of type @a T can be cast to point to a <c>void</c> type
69  * before being passed outside of the module that implements @a T.
70  *
71  * This makes it impossible for anyone outside of the module that implements @a T to
72  * dereference the pointer or access anything about the implementation of @a T. This way,
73  * the module that implements @a T is free to change the implementation of @a T in any
74  * way needed without worrying about breaking code outside of that module.
75  *
76  * The problem with the void pointer type is that it throws away type information. At compile time,
77  * this makes it impossible to detect that a variable with opaque type @a T
78  * has been passed into a function with some other pointer type @a P.
79  *
80  * To overcome this, Legato uses "incomplete types" to implement its opaque types. For example,
81  * there are declarations similar to the following in Legato C API header files:
82  *
83  * @code
84  * // Declare a reference type for referring to Foo objects.
85  * typedef struct le_foo* le_foo_Ref_t;
86  * @endcode
87  *
88  * But "struct le_foo" would @a not be defined in the API header or @a anywhere outside of the
89  * hypothetical "Foo" API's implementation files. This makes "struct le_foo" an "incomplete type"
90  * for all code outside of the Foo API implementation files. Incomplete types can't be used
91  * because the compiler doesn't have enough information about them to generate any code
92  * that uses them. But @a pointers to incomplete types @a can be passed around because the compiler
93  * always knows the pointer size. The compiler knows that one incomplete type
94  * is @a not necessarily interchangeable with another, and it won't allow a pointer to
95  * an incomplete type to be used where a pointer to another non-void type is expected.
96  *
97  * @subsection Handlers and Event-Driven Programs
98  *
99  * "Handler" is an alias for "callback function". Many APIs in the Legato world
100  * use callback functions to notify their clients of asynchronous events. For example, to
101  * register a function called "SigTermHandler" for notification of receipt of a TERM signal,
102  *
103  * @code
104  *
105  * le_sig_SetEventHandler(SIGTERM, SigTermHandler);
106  *
107  * @endcode
108  *
109  * Instead of using "CallbackFunction", "CallbackFunc", or some abbreviation like "CbFn"
110  * (Cub fun? Cubs fan? What?) that is difficult to read and/or remember, "Handler" is used.
111  *
112  * The term "handler" also fits with the event-driven programming style that is favoured in
113  * the Legato world. These callback functions are essentially event handler functions.
114  * That is, the function is called when an event occurs to "handle" that event.
115  *
116  * <HR>
117  *
118  * Copyright (C) Sierra Wireless Inc.
119  */
120 
121 //--------------------------------------------------------------------------------------------------
122 /**
123  * @file legato.h
124  *
125  * This file includes all the commonly-used Legato API header files.
126  * It's provided as a convenience to avoid including
127  * dozens of header files in every source file.
128  *
129  * Copyright (C) Sierra Wireless Inc.
130  */
131 //--------------------------------------------------------------------------------------------------
132 
133 #ifndef LEGATO_H_INCLUDE_GUARD
134 #define LEGATO_H_INCLUDE_GUARD
135 
136 #ifndef _GNU_SOURCE
137 #define _GNU_SOURCE
138 #endif
139 
140 #if defined(__cplusplus) && !defined(__STDC_LIMIT_MACROS)
141 // stdint.h from before C++11 only defines MAX and MIN macros if __STDC_LIMIT_MACROS is defined
142 #define __STDC_LIMIT_MACROS
143 #endif
144 
145 #include <stddef.h>
146 #include <unistd.h>
147 #include <time.h>
148 #include <string.h>
149 #include <stdio.h>
150 #include <stdlib.h>
151 #include <stdint.h>
152 #include <time.h>
153 #include <sys/time.h>
154 #include <stdarg.h>
155 #include <syslog.h>
156 #include <pthread.h>
157 #include <limits.h>
158 #include <errno.h>
159 #include <sys/socket.h>
160 #include <sys/un.h>
161 #include <fcntl.h>
162 #include <sys/sysmacros.h>
163 #include <sys/types.h>
164 #include <sys/syscall.h>
165 #include <signal.h>
166 #include <sys/signalfd.h>
167 #include <sys/wait.h>
168 #include <sys/stat.h>
169 #include <stdbool.h>
170 #include <ctype.h>
171 #include <inttypes.h>
172 #include <dirent.h>
173 #include <sys/reboot.h>
174 #include <sys/timeb.h>
175 #include <sys/mount.h>
176 #include <sys/sysinfo.h>
177 #include <sys/resource.h>
178 #include <mntent.h>
179 #include <grp.h>
180 #include <sys/xattr.h>
181 #include <fts.h>
182 #include <poll.h>
183 #include <sys/epoll.h>
184 #include <sys/prctl.h>
185 #include <sched.h>
186 #include <semaphore.h>
187 #include <math.h>
188 #include <libgen.h>
189 
190 
191 #ifdef __cplusplus
192 extern "C" {
193 #endif
194 
195 #include "le_build_config.h"
196 #include "le_basics.h"
197 #include "le_doublyLinkedList.h"
198 #include "le_singlyLinkedList.h"
199 #include "le_utf8.h"
200 #include "le_log.h"
201 #include "le_mem.h"
202 #include "le_mutex.h"
203 #include "le_clock.h"
204 #include "le_semaphore.h"
205 #include "le_safeRef.h"
206 #include "le_thread.h"
207 #include "le_eventLoop.h"
208 #include "le_fdMonitor.h"
209 #include "le_hashmap.h"
210 #include "le_signals.h"
211 #include "le_args.h"
212 #include "le_timer.h"
213 #include "le_messaging.h"
214 #include "le_test.h"
215 #include "le_pack.h"
216 #include "le_path.h"
217 #include "le_pathIter.h"
218 #include "le_hex.h"
219 #include "le_dir.h"
220 #include "le_fileLock.h"
221 #include "le_json.h"
222 #include "le_tty.h"
223 #include "le_atomFile.h"
224 #include "le_crc.h"
225 #include "le_fs.h"
226 #include "le_rand.h"
227 
228 #ifdef __cplusplus
229 }
230 #endif
231 
232 #endif // LEGATO_H_INCLUDE_GUARD