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 January 21, 2019
  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 "int fd" "const cap_righst_t *rights"
  54 .Ft int
  55 .Fn caph_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds"
  56 .Ft int
  57 .Fn caph_fcntls_limit "int fd" "uint32_t fcntlrights"
  58 .Ft int
  59 .Fn caph_limit_stream "int fd" "int flags"
  60 .Ft int
  61 .Fn caph_limit_stdin "void"
  62 .Ft int
  63 .Fn caph_limit_stderr "void"
  64 .Ft int
  65 .Fn caph_limit_stdout "void"
  66 .Ft int
  67 .Fn caph_limit_stdio "void"
  68 .Ft void
  69 .Fn caph_cache_tzdata "void"
  70 .Ft void
  71 .Fn caph_cache_catpages "void"
  72 .Sh DESCRIPTION
  73 The
  74 .Nm caph_enter ,
  75 .Nm caph_rights_limit ,
  76 .Nm caph_ioctls_limit
  77 and
  78 .Nm caph_fcntls_limit
  79 are respectively equivalent to
  80 .Xr cap_enter 2 ,
  81 .Xr cap_rights_limit 2 ,
  82 .Xr cap_ioctls_limit 2
  83 and
  84 .Xr cap_fcntls_limit 2 ,
  85 it returns success when the kernel is built without support of the capability
  86 mode.
  87 .Pp
  88 The
  89 .Nm caph_enter_casper
  90 is equivalent to the
  91 .Nm caph_enter
  92 it returns success when the system is built without Casper support.
  93 .Pp
  94 The
  95 .Nm capsicum helpers
  96 are a set of a inline functions which simplify modifying programs to use
  97 Capsicum.
  98 The goal is to reduce duplicated code patterns.
  99 The
 100 .Nm capsicum helpers
 101 are part of
 102 .Nm libcapsicum
 103 but there is no need to link to the library.
 104 .Pp
 105 .Fn caph_limit_stream
 106 restricts capabilities on
 107 .Fa fd
 108 to only those needed by POSIX stream objects (that is, FILEs).
 109 .Pp
 110 These flags can be provided:
 111 .Pp
 112 .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
 113 .It Dv CAPH_IGNORE_EBADF
 114 Do not return an error if file descriptor is invalid.
 115 .It Dv CAPH_READ
 116 Set CAP_READ on limited descriptor.
 117 .It Dv CAPH_WRITE
 118 Set CAP_WRITE on limited descriptor.
 119 .El
 120 .Pp
 121 .Fn caph_limit_stdin ,
 122 .Fn caph_limit_stderr
 123 and
 124 .Fn caph_limit_stdout
 125 limit standard descriptors using the
 126 .Nm caph_limit_stream
 127 function.
 128 .Pp
 129 .Fn caph_limit_stdio
 130 limits stdin, stderr and stdout.
 131 .Pp
 132 .Fn caph_cache_tzdata
 133 precaches all timezone data needed to use
 134 .Li libc
 135 local time functions.
 136 .Pp
 137 .Fn caph_cache_catpages
 138 caches Native Language Support (NLS) data.
 139 NLS data is used for localized error printing by
 140 .Xr strerror 3
 141 and
 142 .Xr err 3 ,
 143 among others.
 144 .Ed
 145 .Sh SEE ALSO
 146 .Xr cap_enter 2 ,
 147 .Xr cap_rights_limit 2 ,
 148 .Xr rights 4