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_Import() can be used to import (into an app's container) something from the
   82  *   file system outside of the app's container.  This is used by the @ref toolsHost_sbhelper
   83  *   and @ref toolsTarget_sbtrace interactive sandbox configuration helper tools.
   84  *
   85  * - le_appCtrl_SetDevicePerm() is used to set the permissions of a device file.  This is also
   86  *   used by the @ref toolsHost_sbhelper and @ref toolsTarget_sbtrace interactive sandbox
   87  *   configuration helper tools.
   88  *
   89  * - le_appCtrl_AddTraceAttachHandler() is used to register a call-back handler function to be
   90  *   called whenever the Supervisor has created a process in the app. After calling this call-back,
   91  *   the Supervisor will wait until le_appCtrl_TraceUnblock() is called for that process before
   92  *   allowing it to run.  This gives a debugger the opportunity to attach to the process before
   93  *   running it.
   94  *
   95  * - le_appCtrl_ReleaseRef() releases the reference returned by le_appCtrl_GetRef() and resets all
   96  *   the app control overrides that were set using that reference.
   97  *
   98  * @subsection le_appCtrlApi_debug_syncProcStart Synchronizing Process Start
   99  *
  100  * Some tools need to "attach" to a process (e.g., using the Unix ptrace() API) when the process
  101  * starts. If the process is started by the Supervisor when the app starts, then synchoronization
  102  * can be achieved by calling le_appCtrl_AddTraceAttachHandler() to register a
  103  * "Trace Attach Handler" call-back for the app before starting it. When the Supervisor starts an
  104  * app that has a Trace Attach Handler registered for it, the Supervisor will prepare the app
  105  * container, as usual, and for each app process it starts, it will <c>fork()</c> a child process,
  106  * put it into its runtime container, call the Trace Attach Handler function and block the child
  107  * process before <c>exec()</c>ing the app's program.  When the Trace Attach Handler function
  108  * is called, it is passed the PID of the child process, which the debug tool can use to attach
  109  * to the process before calling le_appCtrl_TraceUnblock() to ask the Supervisor to unblock the
  110  * app's process.
  111  *
  112  * @code
  113  * {
  114  *     ...
  115  *
  116  *     // Get a reference to the app.
  117  *     le_appCtrl_AppRef_t appRef = le_appCtrl_GetRef(appNameStr);
  118  *     if (appRef == NULL)
  119  *     {
  120  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  121  *         exit(EXIT_FAILURE);
  122  *     }
  123  *
  124  *     // Set an attach handler.
  125  *     le_appCtrl_AddTraceAttachHandler(appRef, AttachHandler, NULL);
  126  *
  127  *     // Start the app.
  128  *     le_result_t result = le_appCtrl_Start(appNameStr);
  129  *     if (result != LE_OK)
  130  *     {
  131  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  132  *         exit(EXIT_FAILURE);
  133  *     }
  134  * }
  135  *
  136  * static void AttachHandler
  137  * (
  138  *     le_appCtrl_AppRef_t appRef,         ///< [IN] App reference.
  139  *     int32_t pid,                        ///< [IN] PID of the process to attach to.
  140  *     const char* procNamePtr,            ///< [IN] Name of the process.
  141  *     void* contextPtr                    ///< [IN] Not used.
  142  * )
  143  * {
  144  *     // Attach to the process.
  145  *     ...
  146  *
  147  *     // Ask the supervisor to unblock the process.
  148  *     le_appCtrl_TraceUnblock(appRef, pid);
  149  * }
  150  *
  151  * @endcode
  152  *
  153  * @subsection le_appCtrlApi_debug_suppressProcStart Supressing Start of a Process
  154  *
  155  * It's possible to ask the Supervisor to start an app without starting one or more of the
  156  * app's processes. This is done by calling le_appCtrl_SetRun() to set the "Run" flag to false
  157  * for the process before calling le_appCtrl_Start() to start the app.
  158  *
  159  * @code
  160  * {
  161  *     ...
  162  *
  163  *     // Get a reference to the app.
  164  *     le_appCtrl_AppRef_t appRef = le_appCtrl_GetRef(appNameStr);
  165  *     if (appRef == NULL)
  166  *     {
  167  *         fprintf(stderr, "App '%s' could not be started. Check logs for more info.\n", appNameStr);
  168  *         exit(EXIT_FAILURE);
  169  *     }
  170  *
  171  *     le_appCtrl_SetRun(appRef, procNameStr, false);
  172  *
  173  *     le_appCtrl_Start(appNameStr);
  174  * }
  175  * @endcode
  176  *
  177  * @subsection le_appCtrlApi_debug_importIntoContainer Importing Files Into App Containers
  178  *
  179  * le_appCtrl_Import() can be used to import things from the real root file system into an
  180  * app's run-time container.  le_appCtrl_SetDevicePerm() can be used to set the access permissions
  181  * for a device file such that the app can access it.
  182  *
  183  * @code
  184  * le_result_t r = le_appCtrl_Import(appRef, path);
  185  *
  186  * if (r != LE_OK)
  187  * {
  188  *     fprintf(stderr, "Could not import file '%s'. %s.\n", path, LE_RESULT_TXT(r));
  189  * }
  190  * else if (IsDevice(path))
  191  * {
  192  *     // Give the app read access to the device file.
  193  *     if (le_appCtrl_SetDevicePerm(appRef, path, "r") != LE_OK)
  194  *     {
  195  *         fprintf(stderr, "Could not set permissions to %s for '%s'.\n", permStr, path);
  196  *     }
  197  * }
  198  * @endcode
  199  *
  200  * <HR>
  201  *
  202  * Copyright (C) Sierra Wireless Inc.
  203  */
  204 /**
  205  * @file le_appCtrl_interface.h
  206  *
  207  * Legato @ref c_appCtrl include file.
  208  *
  209  * Copyright (C) Sierra Wireless Inc.
  210  */
  211 
  212 #ifndef LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
  213 #define LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
  214 
  215 
  216 #include "legato.h"
  217 
  218 // Interface specific includes
  219 #include "le_limit_interface.h"
  220 
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Type for handler called when a server disconnects.
  225  */
  226 //--------------------------------------------------------------------------------------------------
  227 typedef void (*le_appCtrl_DisconnectHandler_t)(void *);
  228 
  229 //--------------------------------------------------------------------------------------------------
  230 /**
  231  *
  232  * Connect the current client thread to the service providing this API. Block until the service is
  233  * available.
  234  *
  235  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  236  * called before any other functions in this API.  Normally, ConnectService is automatically called
  237  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  238  *
  239  * This function is created automatically.
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 void le_appCtrl_ConnectService
  243 (
  244     void
  245 );
  246 
  247 //--------------------------------------------------------------------------------------------------
  248 /**
  249  *
  250  * Try to connect the current client thread to the service providing this API. Return with an error
  251  * if the service is not available.
  252  *
  253  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  254  * called before any other functions in this API.  Normally, ConnectService is automatically called
  255  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  256  *
  257  * This function is created automatically.
  258  *
  259  * @return
  260  *  - LE_OK if the client connected successfully to the service.
  261  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  262  *    bound.
  263  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  264  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  265  */
  266 //--------------------------------------------------------------------------------------------------
  267 le_result_t le_appCtrl_TryConnectService
  268 (
  269     void
  270 );
  271 
  272 //--------------------------------------------------------------------------------------------------
  273 /**
  274  * Set handler called when server disconnection is detected.
  275  *
  276  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  277  * to continue without exiting, it should call longjmp() from inside the handler.
  278  */
  279 //--------------------------------------------------------------------------------------------------
  280 void le_appCtrl_SetServerDisconnectHandler
  281 (
  282     le_appCtrl_DisconnectHandler_t disconnectHandler,
  283     void *contextPtr
  284 );
  285 
  286 //--------------------------------------------------------------------------------------------------
  287 /**
  288  *
  289  * Disconnect the current client thread from the service providing this API.
  290  *
  291  * Normally, this function doesn't need to be called. After this function is called, there's no
  292  * longer a connection to the service, and the functions in this API can't be used. For details, see
  293  * @ref apiFilesC_client.
  294  *
  295  * This function is created automatically.
  296  */
  297 //--------------------------------------------------------------------------------------------------
  298 void le_appCtrl_DisconnectService
  299 (
  300     void
  301 );
  302 
  303 
  304 //--------------------------------------------------------------------------------------------------
  305 /**
  306  */
  307 //--------------------------------------------------------------------------------------------------
  308 typedef struct le_appCtrl_App* le_appCtrl_AppRef_t;
  309 
  310 
  311 //--------------------------------------------------------------------------------------------------
  312 /**
  313  * Reference type used by Add/Remove functions for EVENT 'le_appCtrl_TraceAttach'
  314  */
  315 //--------------------------------------------------------------------------------------------------
  316 typedef struct le_appCtrl_TraceAttachHandler* le_appCtrl_TraceAttachHandlerRef_t;
  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 typedef void (*le_appCtrl_TraceAttachHandlerFunc_t)
  326 (
  327     le_appCtrl_AppRef_t appRef,
  328         ///< Ref to the app.
  329     int32_t pid,
  330         ///< PID of a process that can be attached to.
  331     const char* LE_NONNULL procName,
  332         ///< Name of the process name.
  333     void* contextPtr
  334         ///<
  335 );
  336 
  337 //--------------------------------------------------------------------------------------------------
  338 /**
  339  * Gets a reference to an app.
  340  *
  341  * @return
  342  *      Reference to the named app.
  343  *      NULL on error (check logs for errors).
  344  */
  345 //--------------------------------------------------------------------------------------------------
  346 le_appCtrl_AppRef_t le_appCtrl_GetRef
  347 (
  348     const char* LE_NONNULL appName
  349         ///< [IN] Name of the app to get the ref for.
  350 );
  351 
  352 //--------------------------------------------------------------------------------------------------
  353 /**
  354  * Release the reference to an app, resetting all overrides set for this app using other
  355  * functions, like SetRun(), SetDevicePerm(), etc.
  356  */
  357 //--------------------------------------------------------------------------------------------------
  358 void le_appCtrl_ReleaseRef
  359 (
  360     le_appCtrl_AppRef_t appRef
  361         ///< [IN] Ref to the app.
  362 );
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Sets the run flag for a process in an app.
  367  *
  368  * If there is an error this function will kill the calling client.
  369  */
  370 //--------------------------------------------------------------------------------------------------
  371 void le_appCtrl_SetRun
  372 (
  373     le_appCtrl_AppRef_t appRef,
  374         ///< [IN] Ref to the app.
  375     const char* LE_NONNULL procName,
  376         ///< [IN] Process name to set the run flag for.
  377     bool run
  378         ///< [IN] Flag to run the process or not.
  379 );
  380 
  381 //--------------------------------------------------------------------------------------------------
  382 /**
  383  * Imports a file into the app's working directory.
  384  *
  385  * @return
  386  *      LE_OK if successfully imported the file.
  387  *      LE_DUPLICATE if the path conflicts with items already in the app's working directory.
  388  *      LE_NOT_FOUND if the path does not point to a valid file.
  389  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  390  *      LE_FAULT if there was some other error.
  391  *
  392  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  393  *       the function will not return.
  394  */
  395 //--------------------------------------------------------------------------------------------------
  396 le_result_t le_appCtrl_Import
  397 (
  398     le_appCtrl_AppRef_t appRef,
  399         ///< [IN] Ref to the app.
  400     const char* LE_NONNULL path
  401         ///< [IN] Absolute path to the file to import.
  402 );
  403 
  404 //--------------------------------------------------------------------------------------------------
  405 /**
  406  * Sets a device file's permissions.
  407  *
  408  * @return
  409  *      LE_OK if successfully set the device's permissions.
  410  *      LE_NOT_FOUND if the path does not point to a valid device.
  411  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  412  *      LE_FAULT if there was some other error.
  413  *
  414  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  415  *       the function will not return.
  416  */
  417 //--------------------------------------------------------------------------------------------------
  418 le_result_t le_appCtrl_SetDevicePerm
  419 (
  420     le_appCtrl_AppRef_t appRef,
  421         ///< [IN] Ref to the app.
  422     const char* LE_NONNULL path,
  423         ///< [IN] Absolute path to the device.
  424     const char* LE_NONNULL permissions
  425         ///< [IN] Permission string, "r", "w", "rw".
  426 );
  427 
  428 //--------------------------------------------------------------------------------------------------
  429 /**
  430  * Add handler function for EVENT 'le_appCtrl_TraceAttach'
  431  *
  432  * Event that indicates the process is blocked and can be attached to.
  433  */
  434 //--------------------------------------------------------------------------------------------------
  435 le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler
  436 (
  437     le_appCtrl_AppRef_t appRef,
  438         ///< [IN] Ref to the app.
  439     le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr,
  440         ///< [IN] Attach handler to register.
  441     void* contextPtr
  442         ///< [IN]
  443 );
  444 
  445 //--------------------------------------------------------------------------------------------------
  446 /**
  447  * Remove handler function for EVENT 'le_appCtrl_TraceAttach'
  448  */
  449 //--------------------------------------------------------------------------------------------------
  450 void le_appCtrl_RemoveTraceAttachHandler
  451 (
  452     le_appCtrl_TraceAttachHandlerRef_t handlerRef
  453         ///< [IN]
  454 );
  455 
  456 //--------------------------------------------------------------------------------------------------
  457 /**
  458  * Unblocks the traced process.  This should normally be done once the tracer has successfully
  459  * attached to the process.
  460  *
  461  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  462  *       the function will not return.
  463  */
  464 //--------------------------------------------------------------------------------------------------
  465 void le_appCtrl_TraceUnblock
  466 (
  467     le_appCtrl_AppRef_t appRef,
  468         ///< [IN] Ref to the app.
  469     int32_t pid
  470         ///< [IN] PID of the process to unblock.
  471 );
  472 
  473 //--------------------------------------------------------------------------------------------------
  474 /**
  475  * Starts an app.
  476  *
  477  * @return
  478  *      LE_OK if the app is successfully started.
  479  *      LE_DUPLICATE if the app is already running.
  480  *      LE_NOT_FOUND if the app isn't installed.
  481  *      LE_FAULT if there was an error and the app could not be launched.
  482  */
  483 //--------------------------------------------------------------------------------------------------
  484 le_result_t le_appCtrl_Start
  485 (
  486     const char* LE_NONNULL appName
  487         ///< [IN] Name of the app to start.
  488 );
  489 
  490 //--------------------------------------------------------------------------------------------------
  491 /**
  492  * Stops an app.
  493  *
  494  * @return
  495  *      LE_OK if successful.
  496  *      LE_NOT_FOUND if the app could not be found.
  497  */
  498 //--------------------------------------------------------------------------------------------------
  499 le_result_t le_appCtrl_Stop
  500 (
  501     const char* LE_NONNULL appName
  502         ///< [IN] Name of the app to stop.
  503 );
  504 
  505 #endif // LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35
le_appCtrl_AddTraceAttachHandler
le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler(le_appCtrl_AppRef_t appRef, le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr, void *contextPtr)
le_appCtrl_DisconnectHandler_t
void(* le_appCtrl_DisconnectHandler_t)(void *)
Definition: le_appCtrl_interface.h:227
le_appCtrl_SetRun
void le_appCtrl_SetRun(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool run)
le_appCtrl_TryConnectService
le_result_t le_appCtrl_TryConnectService(void)
le_appCtrl_ReleaseRef
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
le_appCtrl_Stop
le_result_t le_appCtrl_Stop(const char *LE_NONNULL appName)
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_limit_interface.h
le_appCtrl_TraceUnblock
void le_appCtrl_TraceUnblock(le_appCtrl_AppRef_t appRef, int32_t pid)
le_appCtrl_GetRef
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *LE_NONNULL appName)
le_appCtrl_RemoveTraceAttachHandler
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
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_interface.h:326
legato.h
le_appCtrl_Start
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)
le_appCtrl_TraceAttachHandlerRef_t
struct le_appCtrl_TraceAttachHandler * le_appCtrl_TraceAttachHandlerRef_t
Definition: le_appCtrl_interface.h:316
le_appCtrl_ConnectService
void le_appCtrl_ConnectService(void)
le_appCtrl_SetServerDisconnectHandler
void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_appCtrl_Import
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path)
le_appCtrl_DisconnectService
void le_appCtrl_DisconnectService(void)