le_appCtrl_interface.h

Go to the documentation of this file.
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
436 (
437  le_appCtrl_AppRef_t appRef,
438  ///< [IN] Ref to the app.
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 //--------------------------------------------------------------------------------------------------
451 (
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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
Definition: le_basics.h:35
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
void le_appCtrl_DisconnectService(void)
struct le_appCtrl_TraceAttachHandler * le_appCtrl_TraceAttachHandlerRef_t
Definition: le_appCtrl_interface.h:316
le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler(le_appCtrl_AppRef_t appRef, le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr, void *contextPtr)
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path)
le_result_t le_appCtrl_Stop(const char *LE_NONNULL appName)
le_result_t le_appCtrl_TryConnectService(void)
void(* le_appCtrl_DisconnectHandler_t)(void *)
Definition: le_appCtrl_interface.h:227
void le_appCtrl_SetRun(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool run)
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
void le_appCtrl_ConnectService(void)
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
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *LE_NONNULL appName)
void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_appCtrl_SetDevicePerm(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path, const char *LE_NONNULL permissions)
void le_appCtrl_TraceUnblock(le_appCtrl_AppRef_t appRef, int32_t pid)