le_process.h

    1 /** @page c_process Process API
    2  *
    3  * @subpage le_process.h "API Reference"
    4  *
    5  * <HR>
    6  * This API provides a means to spawn external processes.  The function le_proc_Execute() takes a
    7  * structure which is populated with the execution parameters and handles the heavy lifting of (on
    8  * Linux) forking and execing as necessary.
    9  *
   10  *
   11  * @code{.c}
   12  * int status;
   13  * le_proc_Parameters_t proc =
   14  * {
   15  *     .executableStr   = "/bin/ls",
   16  *     .argumentsPtr    = { "/bin/ls", "/tmp", NULL },
   17  *     .environmentPtr  = NULL,
   18  *     .detach          = false,
   19  *     .closeFds        = LE_PROC_NO_FDS,
   20  *     .init            = NULL,
   21  *     .userPtr         = NULL
   22  * };
   23  *
   24  * pid_t pid = le_proc_Execute(&proc);
   25  * if (pid < 0)
   26  * {
   27  *     LE_FATAL("Oh no!  Something went wrong (error %d).", errno);
   28  * }
   29  * if (waitpid(pid, &status, 0) > 0)
   30  * {
   31  *     LE_INFO("%s[%d] returned %d", proc.executableStr, (int) pid, status);
   32  * }
   33  * @endcode
   34  *
   35  * <HR>
   36  *
   37  * Copyright (C) Sierra Wireless Inc.
   38  *
   39  */
   40 
   41 /** @file le_process.h
   42  *
   43  * Legato @ref c_process include file.
   44  *
   45  * Copyright (C) Sierra Wireless Inc.
   46  */
   47 
   48 #ifndef LEGATO_PROCESS_INCLUDE_GUARD
   49 #define LEGATO_PROCESS_INCLUDE_GUARD
   50 
   51 /** Value representing no file descriptors. */
   52 #define LE_PROC_NO_FDS  -1
   53 
   54 /** Parameters specifying how to spawn an external process. */
   55 typedef struct le_proc_Parameters
   56 {
   57     const char  *executableStr;     ///< Path to the file to execute.
   58     char *const *argumentsPtr;      ///< NULL-terminated array of arguments to pass to the process.
   59                                     ///< May be NULL.
   60     char *const *environmentPtr;    ///< NULL-terminated array of "var=value" strings to set in the
   61                                     ///< environment of the process.  May be NULL.
   62     bool         detach;            ///< "Detach" the process so that a call to le_proc_Wait() is
   63                                     ///< not required to prevent it from becoming a zombie.
   64     int          closeFds;          ///< Close all open file descriptors in the child at or above
   65                                     ///< the given value.  Set to LE_PROC_NO_FDS to avoid closing
   66                                     ///< any.
   67     void         (*init)(const struct le_proc_Parameters *paramPtr);    ///< Custom function to run
   68                                     ///< right before the executable is exec'd.  Note that only
   69                                     ///< async-signal-safe functions may be called from this
   70                                     ///< callback.
   71     void        *userPtr;           ///< Arbitrary data to include with the parameters.  Only useful
   72                                     ///< if init() is also set.
   73 } le_proc_Parameters_t;
   74 
   75 /**
   76  * Spawn a new process from a given executable.
   77  *
   78  * @return
   79  *      -   0 if the process was spawned in detached mode.
   80  *      -   Greater than 0 if the process was spawned but not detached.  The returned value is the
   81  *          process ID in this case.
   82  *      -   Less than zero if an error occurred.
   83  */
   84 pid_t le_proc_Execute
   85 (
   86     const le_proc_Parameters_t *paramPtr    ///< Properties of the process to spawn.
   87 );
   88 
   89 #endif /* end LEGATO_PROCESS_INCLUDE_GUARD */
le_proc_Parameters_t::environmentPtr
char *const  * environmentPtr
Definition: le_process.h:60
le_proc_Parameters_t::argumentsPtr
char *const  * argumentsPtr
Definition: le_process.h:58
le_proc_Parameters_t::userPtr
void * userPtr
Definition: le_process.h:71
le_proc_Parameters_t::detach
bool detach
Definition: le_process.h:62
le_proc_Parameters_t::executableStr
const char * executableStr
Path to the file to execute. 
Definition: le_process.h:57
le_proc_Parameters_t::closeFds
int closeFds
Definition: le_process.h:64
le_proc_Parameters_t
Definition: le_process.h:55
le_proc_Execute
pid_t le_proc_Execute(const le_proc_Parameters_t *paramPtr)