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_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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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 //--------------------------------------------------------------------------------------------------
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
Definition: le_basics.h:35
void le_appCtrl_SetDebug(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool debug)
le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler(le_appCtrl_AppRef_t appRef, le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr, void *contextPtr)
void(* le_appCtrl_DisconnectHandler_t)(void *)
Definition: le_appCtrl_interface.h:232
void le_appCtrl_SetRun(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL procName, bool run)
le_result_t le_appCtrl_TryConnectService(void)
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
LE_FULL_API void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_result_t le_appCtrl_Stop(const char *LE_NONNULL appName)
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)
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *LE_NONNULL appName)
#define LE_FULL_API
Definition: le_apiFeatures.h:40
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)
void le_appCtrl_ConnectService(void)
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path)
void le_appCtrl_DisconnectService(void)