legato.h

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