lib/libc/gen/cap_rights_get.3

   1 .\"
   2 .\" Copyright (c) 2013 The FreeBSD Foundation
   3 .\"
   4 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd May 5, 2020
  29 .Dt CAP_RIGHTS_GET 3
  30 .Os
  31 .Sh NAME
  32 .Nm cap_rights_get
  33 .Nd obtain capability rights
  34 .Sh LIBRARY
  35 .Lb libc
  36 .Sh SYNOPSIS
  37 .In sys/capsicum.h
  38 .Ft int
  39 .Fn cap_rights_get "int fd" "cap_rights_t *rights"
  40 .Sh DESCRIPTION
  41 The
  42 .Nm cap_rights_get
  43 function allows to obtain current capability rights for the given descriptor.
  44 The function will fill the
  45 .Fa rights
  46 argument with all capability rights if they were not limited or capability
  47 rights configured during the last successful call of
  48 .Xr cap_rights_limit 2
  49 on the given descriptor.
  50 .Pp
  51 The
  52 .Fa rights
  53 argument can be inspected using
  54 .Xr cap_rights_init 3
  55 family of functions.
  56 .Pp
  57 The complete list of the capability rights can be found in the
  58 .Xr rights 4
  59 manual page.
  60 .Sh RETURN VALUES
  61 .Rv -std
  62 .Sh EXAMPLES
  63 The following example demonstrates how to limit file descriptor capability
  64 rights and how to obtain them.
  65 .Bd -literal
  66 cap_rights_t setrights, getrights;
  67 int fd;
  68
  69 memset(&setrights, 0, sizeof(setrights));
  70 memset(&getrights, 0, sizeof(getrights));
  71
  72 fd = open("/tmp/foo", O_RDONLY);
  73 if (fd < 0)
  74         err(1, "open() failed");
  75
  76 cap_rights_init(&setrights, CAP_FSTAT, CAP_READ);
  77 if (cap_rights_limit(fd, &setrights) < 0 && errno != ENOSYS)
  78         err(1, "cap_rights_limit() failed");
  79
  80 if (cap_rights_get(fd, &getrights) < 0 && errno != ENOSYS)
  81         err(1, "cap_rights_get() failed");
  82
  83 assert(memcmp(&setrights, &getrights, sizeof(setrights)) == 0);
  84 .Ed
  85 .Sh ERRORS
  86 .Fn cap_rights_get
  87 succeeds unless:
  88 .Bl -tag -width Er
  89 .It Bq Er EBADF
  90 The
  91 .Fa fd
  92 argument is not a valid active descriptor.
  93 .It Bq Er EFAULT
  94 The
  95 .Fa rights
  96 argument points at an invalid address.
  97 .El
  98 .Sh SEE ALSO
  99 .Xr cap_rights_limit 2 ,
 100 .Xr errno 2 ,
 101 .Xr open 2 ,
 102 .Xr assert 3 ,
 103 .Xr cap_rights_init 3 ,
 104 .Xr err 3 ,
 105 .Xr memcmp 3 ,
 106 .Xr memset 3 ,
 107 .Xr capsicum 4 ,
 108 .Xr rights 4
 109 .Sh HISTORY
 110 The
 111 .Fn cap_rights_get
 112 function first appeared in
 113 .Fx 9.2 .
 114 Support for capabilities and capabilities mode was developed as part of the
 115 .Tn TrustedBSD
 116 Project.
 117 .Sh AUTHORS
 118 This function was created by
 119 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 120 under sponsorship of the FreeBSD Foundation.