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 //--------------------------------------------------------------------------------------------------
  228 /**
  229  * Type for handler called when a server disconnects.
  230  */
  231 //--------------------------------------------------------------------------------------------------
  232 typedef void (*le_appCtrl_DisconnectHandler_t)(void *);
  233 
  234 //--------------------------------------------------------------------------------------------------
  235 /**
  236  *
  237  * Connect the current client thread to the service providing this API. Block until the service is
  238  * available.
  239  *
  240  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  241  * called before any other functions in this API.  Normally, ConnectService is automatically called
  242  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  243  *
  244  * This function is created automatically.
  245  */
  246 //--------------------------------------------------------------------------------------------------
  247 void le_appCtrl_ConnectService
  248 (
  249     void
  250 );
  251 
  252 //--------------------------------------------------------------------------------------------------
  253 /**
  254  *
  255  * Try to connect the current client thread to the service providing this API. Return with an error
  256  * if the service is not available.
  257  *
  258  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  259  * called before any other functions in this API.  Normally, ConnectService is automatically called
  260  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  261  *
  262  * This function is created automatically.
  263  *
  264  * @return
  265  *  - LE_OK if the client connected successfully to the service.
  266  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  267  *    bound.
  268  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  269  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  270  */
  271 //--------------------------------------------------------------------------------------------------
  272 le_result_t le_appCtrl_TryConnectService
  273 (
  274     void
  275 );
  276 
  277 //--------------------------------------------------------------------------------------------------
  278 /**
  279  * Set handler called when server disconnection is detected.
  280  *
  281  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  282  * to continue without exiting, it should call longjmp() from inside the handler.
  283  */
  284 //--------------------------------------------------------------------------------------------------
  285 LE_FULL_API void le_appCtrl_SetServerDisconnectHandler
  286 (
  287     le_appCtrl_DisconnectHandler_t disconnectHandler,
  288     void *contextPtr
  289 );
  290 
  291 //--------------------------------------------------------------------------------------------------
  292 /**
  293  *
  294  * Disconnect the current client thread from the service providing this API.
  295  *
  296  * Normally, this function doesn't need to be called. After this function is called, there's no
  297  * longer a connection to the service, and the functions in this API can't be used. For details, see
  298  * @ref apiFilesC_client.
  299  *
  300  * This function is created automatically.
  301  */
  302 //--------------------------------------------------------------------------------------------------
  303 void le_appCtrl_DisconnectService
  304 (
  305     void
  306 );
  307 
  308 
  309 //--------------------------------------------------------------------------------------------------
  310 /**
  311  */
  312 //--------------------------------------------------------------------------------------------------
  313 
  314 
  315 //--------------------------------------------------------------------------------------------------
  316 /**
  317  * Handler for attaching to a process that is to be traced.  The process is blocked allowing the
  318  * tracer to attach to it.  The tracer must call TraceUnblock() to unblock the traced process.
  319  */
  320 //--------------------------------------------------------------------------------------------------
  321 
  322 
  323 //--------------------------------------------------------------------------------------------------
  324 /**
  325  * Reference type used by Add/Remove functions for EVENT 'le_appCtrl_TraceAttach'
  326  */
  327 //--------------------------------------------------------------------------------------------------
  328 
  329 
  330 //--------------------------------------------------------------------------------------------------
  331 /**
  332  * Gets a reference to an app.
  333  *
  334  * @return
  335  *      Reference to the named app.
  336  *      NULL on error (check logs for errors).
  337  */
  338 //--------------------------------------------------------------------------------------------------
  339 le_appCtrl_AppRef_t le_appCtrl_GetRef
  340 (
  341     const char* LE_NONNULL appName
  342         ///< [IN] Name of the app to get the ref for.
  343 );
  344 
  345 //--------------------------------------------------------------------------------------------------
  346 /**
  347  * Release the reference to an app, resetting all overrides set for this app using other
  348  * functions, like SetRun(), SetDevicePerm(), etc.
  349  */
  350 //--------------------------------------------------------------------------------------------------
  351 void le_appCtrl_ReleaseRef
  352 (
  353     le_appCtrl_AppRef_t appRef
  354         ///< [IN] Ref to the app.
  355 );
  356 
  357 //--------------------------------------------------------------------------------------------------
  358 /**
  359  * Sets the run flag for a process in an app.
  360  *
  361  * If there is an error this function will kill the calling client.
  362  */
  363 //--------------------------------------------------------------------------------------------------
  364 void le_appCtrl_SetRun
  365 (
  366     le_appCtrl_AppRef_t appRef,
  367         ///< [IN] Ref to the app.
  368     const char* LE_NONNULL procName,
  369         ///< [IN] Process name to set the run flag for.
  370     bool run
  371         ///< [IN] Flag to run the process or not.
  372 );
  373 
  374 //--------------------------------------------------------------------------------------------------
  375 /**
  376  * Sets the debug flag for a process in an app.
  377  *
  378  * If there is an error this function will kill the calling client.
  379  */
  380 //--------------------------------------------------------------------------------------------------
  381 void le_appCtrl_SetDebug
  382 (
  383     le_appCtrl_AppRef_t appRef,
  384         ///< [IN] Ref to the app.
  385     const char* LE_NONNULL procName,
  386         ///< [IN] Process name to set the run flag for.
  387     bool debug
  388         ///< [IN] Flag to debug the process or not.
  389 );
  390 
  391 //--------------------------------------------------------------------------------------------------
  392 /**
  393  * Imports a file into the app's working directory.
  394  *
  395  * @return
  396  *      LE_OK if successfully imported the file.
  397  *      LE_DUPLICATE if the path conflicts with items already in the app's working directory.
  398  *      LE_NOT_FOUND if the path does not point to a valid file.
  399  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  400  *      LE_FAULT if there was some other error.
  401  *
  402  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  403  *       the function will not return.
  404  */
  405 //--------------------------------------------------------------------------------------------------
  406 le_result_t le_appCtrl_Import
  407 (
  408     le_appCtrl_AppRef_t appRef,
  409         ///< [IN] Ref to the app.
  410     const char* LE_NONNULL path
  411         ///< [IN] Absolute path to the file to import.
  412 );
  413 
  414 //--------------------------------------------------------------------------------------------------
  415 /**
  416  * Sets a device file's permissions.
  417  *
  418  * @return
  419  *      LE_OK if successfully set the device's permissions.
  420  *      LE_NOT_FOUND if the path does not point to a valid device.
  421  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  422  *      LE_FAULT if there was some other error.
  423  *
  424  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  425  *       the function will not return.
  426  */
  427 //--------------------------------------------------------------------------------------------------
  428 le_result_t le_appCtrl_SetDevicePerm
  429 (
  430     le_appCtrl_AppRef_t appRef,
  431         ///< [IN] Ref to the app.
  432     const char* LE_NONNULL path,
  433         ///< [IN] Absolute path to the device.
  434     const char* LE_NONNULL permissions
  435         ///< [IN] Permission string, "r", "w", "rw".
  436 );
  437 
  438 //--------------------------------------------------------------------------------------------------
  439 /**
  440  * Add handler function for EVENT 'le_appCtrl_TraceAttach'
  441  *
  442  * Event that indicates the process is blocked and can be attached to.
  443  */
  444 //--------------------------------------------------------------------------------------------------
  445 le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler
  446 (
  447     le_appCtrl_AppRef_t appRef,
  448         ///< [IN] Ref to the app.
  449     le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr,
  450         ///< [IN] Attach handler to register.
  451     void* contextPtr
  452         ///< [IN]
  453 );
  454 
  455 //--------------------------------------------------------------------------------------------------
  456 /**
  457  * Remove handler function for EVENT 'le_appCtrl_TraceAttach'
  458  */
  459 //--------------------------------------------------------------------------------------------------
  460 void le_appCtrl_RemoveTraceAttachHandler
  461 (
  462     le_appCtrl_TraceAttachHandlerRef_t handlerRef
  463         ///< [IN]
  464 );
  465 
  466 //--------------------------------------------------------------------------------------------------
  467 /**
  468  * Unblocks the traced process.  This should normally be done once the tracer has successfully
  469  * attached to the process.
  470  *
  471  * @note If the caller is passing an invalid reference to the app, it is a fatal error,
  472  *       the function will not return.
  473  */
  474 //--------------------------------------------------------------------------------------------------
  475 void le_appCtrl_TraceUnblock
  476 (
  477     le_appCtrl_AppRef_t appRef,
  478         ///< [IN] Ref to the app.
  479     int32_t pid
  480         ///< [IN] PID of the process to unblock.
  481 );
  482 
  483 //--------------------------------------------------------------------------------------------------
  484 /**
  485  * Starts an app.
  486  *
  487  * @return
  488  *      LE_OK if the app is successfully started.
  489  *      LE_DUPLICATE if the app is already running.
  490  *      LE_NOT_FOUND if the app isn't installed.
  491  *      LE_FAULT if there was an error and the app could not be launched.
  492  */
  493 //--------------------------------------------------------------------------------------------------
  494 le_result_t le_appCtrl_Start
  495 (
  496     const char* LE_NONNULL appName
  497         ///< [IN] Name of the app to start.
  498 );
  499 
  500 //--------------------------------------------------------------------------------------------------
  501 /**
  502  * Stops an app.
  503  *
  504  * @return
  505  *      LE_OK if successful.
  506  *      LE_NOT_FOUND if the app could not be found.
  507  */
  508 //--------------------------------------------------------------------------------------------------
  509 le_result_t le_appCtrl_Stop
  510 (
  511     const char* LE_NONNULL appName
  512         ///< [IN] Name of the app to stop.
  513 );
  514 
  515 #endif // LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35
le_appCtrl_SetDebug
void le_appCtrl_SetDebug(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool debug)
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:232
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_SetServerDisconnectHandler
LE_FULL_API void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
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_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
le_appCtrl_RemoveTraceAttachHandler
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
le_appCtrl_Start
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)
le_appCtrl_ConnectService
void le_appCtrl_ConnectService(void)
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)