lib/libcapsicum/capsicum_helpers.3

   1 .\" Copyright (c) 2016 Mariusz Zaborski <oshogbo@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 4, 2018
  28 .Dt CAPSICUM_HELPERS 3
  29 .Os
  30 .Sh NAME
  31 .Nm caph_limit_stream ,
  32 .Nm caph_limit_stdin ,
  33 .Nm caph_limit_stderr ,
  34 .Nm caph_limit_stdout ,
  35 .Nm caph_limit_stdio ,
  36 .Nm caph_cache_tzdata ,
  37 .Nm caph_cache_catpages ,
  38 .Nm caph_enter ,
  39 .Nm caph_enter_casper ,
  40 .Nm caph_rights_limit ,
  41 .Nm caph_ioctls_limit ,
  42 .Nm caph_fcntls_limit
  43 .Nd "set of the capsicum helpers, part of the libcapsicum"
  44 .Sh LIBRARY
  45 .Lb libcapsicum
  46 .Sh SYNOPSIS
  47 .In capsicum_helpers.h
  48 .Ft int
  49 .Fn caph_enter "void"
  50 .Ft int
  51 .Fn caph_enter_casper "void"
  52 .Ft int
  53 .Fn caph_rights_limit "inf fd" "const cap_righst_t *rights"
  54 .Ft int
  55 .Fn caph_ioctls_limit "inf fd" "const unsigned long *cmds" "size_t ncmds"
  56 .Ft int
  57 .Fn caph_fcntls_limit "inf fd" "uint32_t fcntlrights"
  58 .Ft int
  59 .Fn caph_limit_stdin "void"
  60 .Ft int
  61 .Fn caph_limit_stderr "void"
  62 .Ft int
  63 .Fn caph_limit_stdout "void"
  64 .Ft int
  65 .Fn caph_limit_stdio "void"
  66 .Ft void
  67 .Fn caph_cache_tzdata "void"
  68 .Ft void
  69 .Fn caph_cache_catpages "void"
  70 .Sh DESCRIPTION
  71 The
  72 .Nm caph_enter ,
  73 .Nm caph_rights_limit ,
  74 .Nm caph_ioctls_limit
  75 and
  76 .Nm caph_fcntls_limit
  77 are respectively equivalent to
  78 .Xr cap_enter 2 ,
  79 .Xr cap_rights_limit 2 ,
  80 .Xr cap_ioctls_limit 2
  81 and
  82 .Xr cap_fcntls_limit 2 ,
  83 it returns success when the kernel is built without support of the capability
  84 mode.
  85 .Pp
  86 The
  87 .Nm caph_enter_casper
  88 is equivalent to the
  89 .Nm caph_enter
  90 it returns success when the system is built without Casper support.
  91 .Pp
  92 The
  93 .Nm capsicum helpers
  94 are a set of a inline functions which simplify modifying programs to use
  95 Capsicum.
  96 The goal is to reduce duplicated code patterns.
  97 The
  98 .Nm capsicum helpers
  99 are part of
 100 .Nm libcapsicum
 101 but there is no need to link to the library.
 102 .Pp
 103 .Fn caph_limit_stream
 104 restricts capabilities on
 105 .Fa fd
 106 to only those needed by POSIX stream objects (that is, FILEs).
 107 .Pp
 108 These flags can be provided:
 109 .Pp
 110 .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
 111 .It Dv CAPH_IGNORE_EBADF
 112 Do not return an error if file descriptor is invalid.
 113 .It Dv CAPH_READ
 114 Set CAP_READ on limited descriptor.
 115 .It Dv CAPH_WRITE
 116 Set CAP_WRITE on limited descriptor.
 117 .El
 118 .Pp
 119 .Fn caph_limit_stdin ,
 120 .Fn caph_limit_stderr
 121 and
 122 .Fn caph_limit_stdout
 123 limit standard descriptors using the
 124 .Nm caph_limit_stream
 125 function.
 126 .Pp
 127 .Fn caph_limit_stdio
 128 limits stdin, stderr and stdout.
 129 .Pp
 130 .Fn caph_cache_tzdata
 131 precaches all timezone data needed to use
 132 .Li libc
 133 local time functions.
 134 .Pp
 135 .Fn caph_cache_catpages
 136 caches Native Language Support (NLS) data.
 137 NLS data is used for localized error printing by
 138 .Xr strerror 3
 139 and
 140 .Xr err 3 ,
 141 among others.
 142 .Ed
 143 .Sh SEE ALSO
 144 .Xr cap_enter 2 ,
 145 .Xr cap_rights_limit 2 ,
 146 .Xr rights 4