diff options
Diffstat (limited to 'doc/cap_launch.3')
| -rw-r--r-- | doc/cap_launch.3 | 37 |
1 files changed, 23 insertions, 14 deletions
diff --git a/doc/cap_launch.3 b/doc/cap_launch.3 index 6d9b8f7..2d186eb 100644 --- a/doc/cap_launch.3 +++ b/doc/cap_launch.3 @@ -1,24 +1,30 @@ .TH CAP_LAUNCH 3 "2021-08-01" "" "Linux Programmer's Manual" .SH NAME +cap_new_launcher, cap_func_launcher, cap_launcher_callback, \ +cap_launcher_set_mode, cap_launcher_set_iab, cap_launcher_set_chroot, \ +cap_launch, cap_launcher_setuid, cap_launcher_setgroups \ +\- libcap launch functionality +.SH SYNOPSYS .nf #include <sys/capability.h> -cap_launch_t cap_new_launcher(const char *arg0, const char * const *argv, - const char * const *envp); +cap_launch_t cap_new_launcher(const char *arg0, const char *const *argv, + const char *const *envp); cap_launch_t cap_func_launcher(int (callback_fn)(void *detail)); -void cap_launcher_callback(cap_launch_t attr, +int cap_launcher_callback(cap_launch_t attr, int (callback_fn)(void *detail)); -void cap_launcher_set_mode(cap_launch_t attr, cap_mode_t flavor); +int cap_launcher_set_mode(cap_launch_t attr, cap_mode_t flavor); cap_iab_t cap_launcher_set_iab(cap_launch_t attr, cap_iab_t iab); -void cap_launcher_set_chroot(cap_launch_t attr, const char *chroot); +int cap_launcher_set_chroot(cap_launch_t attr, const char *chroot); #include <sys/types.h> pid_t cap_launch(cap_launch_t attr, void *detail); -void cap_launcher_setuid(cap_launch_t attr, uid_t uid); -void cap_launcher_setgroups(cap_launch_t attr, gid_t gid, +int cap_launcher_setuid(cap_launch_t attr, uid_t uid); +int cap_launcher_setgroups(cap_launch_t attr, gid_t gid, + int ngroups, const gid_t *groups); .fi .sp Link with \fI\-lcap\fP. @@ -76,9 +82,9 @@ outside the main process of the calling application. An example of this would be to allocate detail as follows: .nf - const *char[] args = { "echo", "hello", NULL }; + const char *args[] = { "echo", "hello", NULL }; cap_launch_t cmd = cap_new_launcher("/usr/bin/echo", args, NULL); - int *detail = mmap(NULL, sizeof(int), PROT_READ | PROT_WRITE, + int *detail = mmap(NULL, sizeof(int), PROT_READ | PROT_WRITE, MAP_SHARED | MAP_ANONYMOUS, -1, 0); cap_launcher_callback(cmd, &answer_detail_fn); *detail = 41; @@ -86,7 +92,7 @@ this would be to allocate detail as follows: printf("launcher callback set detail to %d\\n", *detail); munmap(detail, sizeof(int)); -.if +.fi .PP Unless modified by the callback function, the launched code will execute with the capability and other security context of the @@ -124,9 +130,11 @@ the launcher. Calling this function with an IAB value of NULL will configure the launcher to not set an IAB value (the default). See \fBcap_iab\fP(3) for details on the IAB set. Note, the launcher is associated directly with the supplied \fIiab\fP value, and does not -make a copy of it. Set with NULL to regain control over the memory -associated with that IAB value, otherwise the IAB value will be -\fBcap_free\fI()\fP'd when the launcher is. +make a copy of it. This iab value is locked to the laucher and cannot +be modified while associated with the launcher. Set with NULL to +regain control over the memory associated with that IAB value, +otherwise the IAB value will be \fBcap_free\fI()\fP'd when the +launcher is. .sp .BR cap_launcher_set_chroot () This function causes the launched program executable to be invoked @@ -153,7 +161,8 @@ should be considered an error. .BR cap_launch () returns -1 in the case of an error. .PP -In all such cases consult +In all such cases a return value of 0 implies success. In other cases, +consult .BR errno (3) for further details. .SH "HISTORY" |