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