le_appCtrl_interface.h

    1 
    2 
    3 /*
    4  * ====================== WARNING ======================
    5  *
    6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
    7  * DO NOT MODIFY IN ANY WAY.
    8  *
    9  * ====================== WARNING ======================
   10  */
   11 
   12 /**
   13  * @page c_appCtrl App Control API
   14  *
   15  * @ref le_appCtrl_interface.h "API Reference"
   16  *
   17  * API for controlling (starting, stopping, and debugging) apps.
   18  *
   19  * @warning This API should only be made available to privileged users because it allows
   20  *          denial of service and arbitrary program execution in other apps.  It also gives the
   21  *          user the ability to grant themselves access to any file, socket or device on the
   22  *          target system.
   23  *
   24  * @section le_appCtrlApi_binding Binding
   25  *
   26  * You can use a definition @c .adef file to bind your client-side app and component to the
   27  * server-side App Control service.
   28  *
   29  * This code sample shows how to bind an app to this service:
   30  * @code
   31  * bindings
   32  * {
   33  *     myExe.myComp.le_appCtrl -> <root>.le_appCtrl
   34  * }
   35  * @endcode
   36  *
   37  * See @ref defFilesAdef for details.
   38  *
   39  *
   40  * @section le_appCtrlApi_start Start App
   41  *
   42  * Use le_appCtrl_Start() (const char * appName) to start an app.
   43  *
   44  * The code sample shows how to use the App Control service to start an app:
   45  *
   46  * @code
   47  *  le_result_t result = le_appCtrl_Start("myApp");
   48  * @endcode
   49  *
   50  * where @c myApp is the name of the app.
   51  *
   52  *
   53  * @section le_appCtrlApi_stop Stop App
   54  *
   55  * Use le_appCtrl_Stop() to stop an app.
   56  *
   57  * This code sample shows how to use the App Control service to stop an app.
   58  *
   59  * @code
   60  *  le_result_t result = le_appCtrl_Stop("myApp");
   61  * @endcode
   62  *
   63  * where @c myApp is the name of the app.
   64  *
   65  *
   66  * @section le_appCtrlApi_debug Debugging Features
   67  *
   68  * Several functions are provided to support the construction of tools for debugging apps.
   69  * These functions are used by the @c appCtrl and @ref toolsTarget_sbtrace tools. See the
   70  * implementations of those tools (under <c>framework/tools/target/linux</c>) for real-world
   71  * examples of how these functions can be used.
   72  *
   73  * - le_appCtrl_GetRef() can be used to get a reference to an app.  This reference can then be used
   74  *   to apply overrides to the way that app will be started when le_appCtrl_Start() is called.
   75  *
   76  * - le_appCtrl_SetRun() can be used to set or clear the "run" flag for a given process in the app.
   77  *   Clearing the "run" flag will result in that process not being started when the app starts.
   78  *   This can be used to start an app without one or more processes that are to be started later
   79  *   using strace or gdbserver, for example.
   80  *
   81  * - le_appCtrl_SetDebug() can be used to set or clear the "debug" flag for a given process in the
   82  *   app.  Setting the "debug" flag will result in the process being started in the stopped state.
   83  *   A debugger can then be attached to the process.
   84  *
   85  * - le_appCtrl_Import() can be used to import (into an app's container) something from the
   86  *   file system outside of the app's container.  This is used by the @ref toolsHost_sbhelper
   87  *   and @ref toolsTarget_sbtrace interactive sandbox configuration helper tools.
   88  *
   89  * - le_appCtrl_SetDevicePerm() is used to set the permissions of a device file.  This is also
   90  *   used by the @ref toolsHost_sbhelper and @ref toolsTarget_sbtrace interactive sandbox
   91  *   configuration helper tools.
   92  *
   93  * - le_appCtrl_AddTraceAttachHandler() is used to register a call-back handler function to be
   94  *   called whenever the Supervisor has created a process in the app. After calling this call-back,
   95  *   the Supervisor will wait until le_appCtrl_TraceUnblock() is called for that process before
   96  *   allowing it to run.  This gives a debugger the opportunity to attach to the process before
   97  *   running it.
   98  *
   99  * - le_appCtrl_ReleaseRef() releases the reference returned by le_appCtrl_GetRef() and resets all
  100  *   the app control overrides that were set using that reference.
  101  *
  102  * @subsection le_appCtrlApi_debug_syncProcStart Synchronizing Process Start
  103  *
  104  * Some tools need to "attach" to a process (e.g., using the Unix ptrace() API) when the process
  105  * starts. If the process is started by the Supervisor when the app starts, then synchoronization
  106  * can be achieved by calling le_appCtrl_AddTraceAttachHandler() to register a
  107  * "Trace Attach Handler" call-back for the app before starting it. When the Supervisor starts an
  108  * app that has a Trace Attach Handler registered for it, the Supervisor will prepare the app
  109  * container, as usual, and for each app process it starts, it will <c>fork()</c> a child process,
  110  * put it into its runtime container, call the Trace Attach Handler function and block the child
  111  * process before <c>exec()</c>ing the app's program.  When the Trace Attach Handler function
  112  * is called, it is passed the PID of the child process, which the debug tool can use to attach
  113  * to the process before calling le_appCtrl_TraceUnblock() to ask the Supervisor to unblock the
  114  * app's process.
  115  *
  116  * @code
  117  * {
  118  *     ...
  119  *
  120  *     // Get a reference to the app.
  121  *     le_appCtrl_AppRef_t appRef = le_appCtrl_GetRef(appNameStr);
  122  *     if (appRef == NULL)
  123  *     {
  124  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  125  *         exit(EXIT_FAILURE);
  126  *     }
  127  *
  128  *     // Set an attach handler.
  129  *     le_appCtrl_AddTraceAttachHandler(appRef, AttachHandler, NULL);
  130  *
  131  *     // Start the app.
  132  *     le_result_t result = le_appCtrl_Start(appNameStr);
  133  *     if (result != LE_OK)
  134  *     {
  135  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  136  *         exit(EXIT_FAILURE);
  137  *     }
  138  * }
  139  *
  140  * static void AttachHandler
  141  * (
  142  *     le_appCtrl_AppRef_t appRef,         ///< [IN] App reference.
  143  *     int32_t pid,                        ///< [IN] PID of the process to attach to.
  144  *     const char* procNamePtr,            ///< [IN] Name of the process.
  145  *     void* contextPtr                    ///< [IN] Not used.
  146  * )
  147  * {
  148  *     // Attach to the process.
  149  *     ...
  150  *
  151  *     // Ask the supervisor to unblock the process.
  152  *     le_appCtrl_TraceUnblock(appRef, pid);
  153  * }
  154  *
  155  * @endcode
  156  *
  157  * @subsection le_appCtrlApi_debug_suppressProcStart Supressing Start of a Process
  158  *
  159  * It's possible to ask the Supervisor to start an app without starting one or more of the
  160  * app's processes. This is done by calling le_appCtrl_SetRun() to set the "Run" flag to false
  161  * for the process before calling le_appCtrl_Start() to start the app.
  162  *
  163  * @code
  164  * {
  165  *     ...
  166  *
  167  *     // Get a reference to the app.
  168  *     le_appCtrl_AppRef_t appRef = le_appCtrl_GetRef(appNameStr);
  169  *     if (appRef == NULL)
  170  *     {
  171  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  172  *         exit(EXIT_FAILURE);
  173  *     }
  174  *
  175  *     le_appCtrl_SetRun(appRef, procNameStr, false);
  176  *
  177  *     le_appCtrl_Start(appNameStr);
  178  * }
  179  * @endcode
  180  *
  181  * @subsection le_appCtrlApi_debug_importIntoContainer Importing Files Into App Containers
  182  *
  183  * le_appCtrl_Import() can be used to import things from the real root file system into an
  184  * app's run-time container.  le_appCtrl_SetDevicePerm() can be used to set the access permissions
  185  * for a device file such that the app can access it.
  186  *
  187  * @code
  188  * le_result_t r = le_appCtrl_Import(appRef, path);
  189  *
  190  * if (r != LE_OK)
  191  * {
  192  *     fprintf(stderr, "Could not import file '%s'. %s.\n", path, LE_RESULT_TXT(r));
  193  * }
  194  * else if (IsDevice(path))
  195  * {
  196  *     // Give the app read access to the device file.
  197  *     if (le_appCtrl_SetDevicePerm(appRef, path, "r") != LE_OK)
  198  *     {
  199  *         fprintf(stderr, "Could not set permissions to %s for '%s'.\n", permStr, path);
  200  *     }
  201  * }
  202  * @endcode
  203  *
  204  * <HR>
  205  *
  206  * Copyright (C) Sierra Wireless Inc.
  207  */
  208 /**
  209  * @file le_appCtrl_interface.h
  210  *
  211  * Legato @ref c_appCtrl include file.
  212  *
  213  * Copyright (C) Sierra Wireless Inc.
  214  */
  215 
  216 #ifndef LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
  217 #define LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
  218 
  219 
  220 #include "legato.h"
  221 
  222 // Interface specific includes
  223 #include "le_limit_interface.h"
  224 
  225 // Internal includes for this interface
  226 #include "le_appCtrl_common.h"
  227 /** @addtogroup le_appCtrl le_appCtrl API Reference
  228  * @{
  229  * @file le_appCtrl_common.h
  230  * @file le_appCtrl_interface.h **/
  231 //--------------------------------------------------------------------------------------------------
  232 /**
  233  * Type for handler called when a server disconnects.
  234  */
  235 //--------------------------------------------------------------------------------------------------
  236 typedef void (*le_appCtrl_DisconnectHandler_t)(void *);
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  *
  241  * Connect the current client thread to the service providing this API. Block until the service is
  242  * available.
  243  *
  244  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  245  * called before any other functions in this API.  Normally, ConnectService is automatically called
  246  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  247  *
  248  * This function is created automatically.
  249  */
  250 //--------------------------------------------------------------------------------------------------
  251 void le_appCtrl_ConnectService
  252 (
  253     void
  254 );
  255 
  256 //--------------------------------------------------------------------------------------------------
  257 /**
  258  *
  259  * Try to connect the current client thread to the service providing this API. Return with an error
  260  * if the service is not available.
  261  *
  262  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  263  * called before any other functions in this API.  Normally, ConnectService is automatically called
  264  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  265  *
  266  * This function is created automatically.
  267  *
  268  * @return
  269  *  - LE_OK if the client connected successfully to the service.
  270  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  271  *    bound.
  272  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  273  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 le_result_t le_appCtrl_TryConnectService
  277 (
  278     void
  279 );
  280 
  281 //--------------------------------------------------------------------------------------------------
  282 /**
  283  * Set handler called when server disconnection is detected.
  284  *
  285  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  286  * to continue without exiting, it should call longjmp() from inside the handler.
  287  */
  288 //--------------------------------------------------------------------------------------------------
  289 LE_FULL_API void le_appCtrl_SetServerDisconnectHandler
  290 (
  291     le_appCtrl_DisconnectHandler_t disconnectHandler,
  292     void *contextPtr
  293 );
  294 
  295 //--------------------------------------------------------------------------------------------------
  296 /**
  297  *
  298  * Disconnect the current client thread from the service providing this API.
  299  *
  300  * Normally, this function doesn't need to be called. After this function is called, there's no
  301  * longer a connection to the service, and the functions in this API can't be used. For details, see
  302  * @ref apiFilesC_client.
  303  *
  304  * This function is created automatically.
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 void le_appCtrl_DisconnectService
  308 (
  309     void
  310 );
  311 
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  */
  316 //--------------------------------------------------------------------------------------------------
  317 
  318 
  319 //--------------------------------------------------------------------------------------------------
  320 /**
  321  * Handler for attaching to a process that is to be traced.  The process is blocked allowing the
  322  * tracer to attach to it.  The tracer must call TraceUnblock() to unblock the traced process.
  323  */
  324 //--------------------------------------------------------------------------------------------------
  325 
  326 
  327 //--------------------------------------------------------------------------------------------------
  328 /**
  329  * Reference type used by Add/Remove functions for EVENT 'le_appCtrl_TraceAttach'
  330  */
  331 //--------------------------------------------------------------------------------------------------
  332 
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Gets a reference to an app.
  337  *
  338  * @return
  339  *      Reference to the named app.
  340  *      NULL on error (check logs for errors).
  341  */
  342 //--------------------------------------------------------------------------------------------------
  343 le_appCtrl_AppRef_t le_appCtrl_GetRef
  344 (
  345     const char* LE_NONNULL appName
  346         ///< [IN] Name of the app to get the ref for.
  347 );
  348 
  349 //--------------------------------------------------------------------------------------------------
  350 /**
  351  * Release the reference to an app, resetting all overrides set for this app using other
  352  * functions, like SetRun(), SetDevicePerm(), etc.
  353  */
  354 //--------------------------------------------------------------------------------------------------
  355 void le_appCtrl_ReleaseRef
  356 (
  357     le_appCtrl_AppRef_t appRef
  358         ///< [IN] Ref to the app.
  359 );
  360 
  361 //--------------------------------------------------------------------------------------------------
  362 /**
  363  * Sets the run flag for a process in an app.
  364  *
  365  * If there is an error this function will kill the calling client.
  366  */
  367 //--------------------------------------------------------------------------------------------------
  368 void le_appCtrl_SetRun
  369 (
  370     le_appCtrl_AppRef_t appRef,
  371         ///< [IN] Ref to the app.
  372     const char* LE_NONNULL procName,
  373         ///< [IN] Process name to set the run flag for.
  374     bool run
  375         ///< [IN] Flag to run the process or not.
  376 );
  377 
  378 //--------------------------------------------------------------------------------------------------
  379 /**
  380  * Sets the debug flag for a process in an app.
  381  *
  382  * If there is an error this function will kill the calling client.
  383  */
  384 //--------------------------------------------------------------------------------------------------
  385 void le_appCtrl_SetDebug
  386 (
  387     le_appCtrl_AppRef_t appRef,
  388         ///< [IN] Ref to the app.
  389     const char* LE_NONNULL procName,
  390         ///< [IN] Process name to set the run flag for.
  391     bool debug
  392         ///< [IN] Flag to debug the process or not.
  393 );
  394 
  395 //--------------------------------------------------------------------------------------------------
  396 /**
  397  * Imports a file into the app's working directory.
  398  *
  399  * @return
  400  *      LE_OK if successfully imported the file.
  401  *      LE_DUPLICATE if the path conflicts with items already in the app's working directory.
  402  *      LE_NOT_FOUND if the path does not point to a valid file.
  403  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  404  *      LE_FAULT if there was some other error.
  405  *
  406  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  407  *       the function will not return.
  408  */
  409 //--------------------------------------------------------------------------------------------------
  410 le_result_t le_appCtrl_Import
  411 (
  412     le_appCtrl_AppRef_t appRef,
  413         ///< [IN] Ref to the app.
  414     const char* LE_NONNULL path
  415         ///< [IN] Absolute path to the file to import.
  416 );
  417 
  418 //--------------------------------------------------------------------------------------------------
  419 /**
  420  * Sets a device file's permissions.
  421  *
  422  * @return
  423  *      LE_OK if successfully set the device's permissions.
  424  *      LE_NOT_FOUND if the path does not point to a valid device.
  425  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  426  *      LE_FAULT if there was some other error.
  427  *
  428  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  429  *       the function will not return.
  430  */
  431 //--------------------------------------------------------------------------------------------------
  432 le_result_t le_appCtrl_SetDevicePerm
  433 (
  434     le_appCtrl_AppRef_t appRef,
  435         ///< [IN] Ref to the app.
  436     const char* LE_NONNULL path,
  437         ///< [IN] Absolute path to the device.
  438     const char* LE_NONNULL permissions
  439         ///< [IN] Permission string, "r", "w", "rw".
  440 );
  441 
  442 //--------------------------------------------------------------------------------------------------
  443 /**
  444  * Add handler function for EVENT 'le_appCtrl_TraceAttach'
  445  *
  446  * Event that indicates the process is blocked and can be attached to.
  447  */
  448 //--------------------------------------------------------------------------------------------------
  449 le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler
  450 (
  451     le_appCtrl_AppRef_t appRef,
  452         ///< [IN] Ref to the app.
  453     le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr,
  454         ///< [IN] Attach handler to register.
  455     void* contextPtr
  456         ///< [IN]
  457 );
  458 
  459 //--------------------------------------------------------------------------------------------------
  460 /**
  461  * Remove handler function for EVENT 'le_appCtrl_TraceAttach'
  462  */
  463 //--------------------------------------------------------------------------------------------------
  464 void le_appCtrl_RemoveTraceAttachHandler
  465 (
  466     le_appCtrl_TraceAttachHandlerRef_t handlerRef
  467         ///< [IN]
  468 );
  469 
  470 //--------------------------------------------------------------------------------------------------
  471 /**
  472  * Unblocks the traced process.  This should normally be done once the tracer has successfully
  473  * attached to the process.
  474  *
  475  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  476  *       the function will not return.
  477  */
  478 //--------------------------------------------------------------------------------------------------
  479 void le_appCtrl_TraceUnblock
  480 (
  481     le_appCtrl_AppRef_t appRef,
  482         ///< [IN] Ref to the app.
  483     int32_t pid
  484         ///< [IN] PID of the process to unblock.
  485 );
  486 
  487 //--------------------------------------------------------------------------------------------------
  488 /**
  489  * Starts an app.
  490  *
  491  * @return
  492  *      LE_OK if the app is successfully started.
  493  *      LE_DUPLICATE if the app is already running.
  494  *      LE_NOT_FOUND if the app isn't installed.
  495  *      LE_FAULT if there was an error and the app could not be launched.
  496  */
  497 //--------------------------------------------------------------------------------------------------
  498 le_result_t le_appCtrl_Start
  499 (
  500     const char* LE_NONNULL appName
  501         ///< [IN] Name of the app to start.
  502 );
  503 
  504 //--------------------------------------------------------------------------------------------------
  505 /**
  506  * Stops an app.
  507  *
  508  * @return
  509  *      LE_OK if successful.
  510  *      LE_NOT_FOUND if the app could not be found.
  511  */
  512 //--------------------------------------------------------------------------------------------------
  513 le_result_t le_appCtrl_Stop
  514 (
  515     const char* LE_NONNULL appName
  516         ///< [IN] Name of the app to stop.
  517 );
  518 
  519 /** @} **/
  520 
  521 #endif // LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
le_appCtrl_SetServerDisconnectHandler
LE_FULL_API void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t
le_result_t
Definition: le_basics.h:46
le_appCtrl_DisconnectHandler_t
void(* le_appCtrl_DisconnectHandler_t)(void *)
Definition: le_appCtrl_interface.h:236
le_appCtrl_SetDevicePerm
le_result_t le_appCtrl_SetDevicePerm(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path, const char *LE_NONNULL permissions)
le_appCtrl_TraceUnblock
void le_appCtrl_TraceUnblock(le_appCtrl_AppRef_t appRef, int32_t pid)
le_appCtrl_TryConnectService
le_result_t le_appCtrl_TryConnectService(void)
le_appCtrl_GetRef
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *LE_NONNULL appName)
le_appCtrl_SetRun
void le_appCtrl_SetRun(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool run)
le_appCtrl_ReleaseRef
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
le_appCtrl_AddTraceAttachHandler
le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler(le_appCtrl_AppRef_t appRef, le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr, void *contextPtr)
le_appCtrl_TraceAttachHandlerFunc_t
void(* le_appCtrl_TraceAttachHandlerFunc_t)(le_appCtrl_AppRef_t appRef, int32_t pid, const char *LE_NONNULL procName, void *contextPtr)
Definition: le_appCtrl_common.h:53
le_appCtrl_Import
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path)
le_appCtrl_common.h
le_limit_interface.h
le_appCtrl_RemoveTraceAttachHandler
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
legato.h
le_appCtrl_Stop
le_result_t le_appCtrl_Stop(const char *LE_NONNULL appName)
le_appCtrl_ConnectService
void le_appCtrl_ConnectService(void)
le_appCtrl_TraceAttachHandlerRef_t
struct le_appCtrl_TraceAttachHandler * le_appCtrl_TraceAttachHandlerRef_t
Definition: le_appCtrl_common.h:43
le_appCtrl_DisconnectService
void le_appCtrl_DisconnectService(void)
le_appCtrl_SetDebug
void le_appCtrl_SetDebug(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool debug)
le_appCtrl_Start
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)