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 July 18, 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 .Nd "set of the capsicum helpers, part of the libcapsicum"
  39 .Sh LIBRARY
  40 .Lb libcapsicum
  41 .Sh SYNOPSIS
  42 .In capsicum_helpers.h
  43 .Ft int
  44 .Fn caph_enter "void"
  45 .Ft int
  46 .Fn caph_enter_casper "void"
  47 .Ft int
  48 .Fn caph_limit_stream "int fd" "int flags"
  49 .Ft int
  50 .Fn caph_limit_stdin "void"
  51 .Ft int
  52 .Fn caph_limit_stderr "void"
  53 .Ft int
  54 .Fn caph_limit_stdout "void"
  55 .Ft int
  56 .Fn caph_limit_stdio "void"
  57 .Ft void
  58 .Fn caph_cache_tzdata "void"
  59 .Ft void
  60 .Fn caph_cache_catpages "void"
  61 .Sh DESCRIPTION
  62 The
  63 .Nm caph_enter
  64 is equivalent to the
  65 .Xr cap_enter 2
  66 it returns success when the kernel is built without support of the capability
  67 mode.
  68 .Pp
  69 The
  70 .Nm caph_enter_casper
  71 is equivalent to the
  72 .Nm caph_enter
  73 it returns success when the system is built without Casper support.
  74 .Pp
  75 The
  76 .Nm capsicum helpers
  77 are a set of a inline functions which simplify modifying programs to use
  78 Capsicum.
  79 The goal is to reduce duplicated code patterns.
  80 The
  81 .Nm capsicum helpers
  82 are part of
  83 .Nm libcapsicum
  84 but there is no need to link to the library.
  85 .Pp
  86 .Fn caph_limit_stream
  87 restricts capabilities on
  88 .Fa fd
  89 to only those needed by POSIX stream objects (that is, FILEs).
  90 .Pp
  91 These flags can be provided:
  92 .Pp
  93 .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
  94 .It Dv CAPH_IGNORE_EBADF
  95 Do not return an error if file descriptor is invalid.
  96 .It Dv CAPH_READ
  97 Set CAP_READ on limited descriptor.
  98 .It Dv CAPH_WRITE
  99 Set CAP_WRITE on limited descriptor.
 100 .El
 101 .Pp
 102 .Fn caph_limit_stdin ,
 103 .Fn caph_limit_stderr
 104 and
 105 .Fn caph_limit_stdout
 106 limit standard descriptors using the
 107 .Nm caph_limit_stream
 108 function.
 109 .Pp
 110 .Fn caph_limit_stdio
 111 limits stdin, stderr and stdout.
 112 .Pp
 113 .Fn caph_cache_tzdata
 114 precaches all timezone data needed to use
 115 .Li libc
 116 local time functions.
 117 .Pp
 118 .Fn caph_cache_catpages
 119 caches Native Language Support (NLS) data.
 120 NLS data is used for localized error printing by
 121 .Xr strerror 3
 122 and
 123 .Xr err 3 ,
 124 among others.
 125 .Ed
 126 .Sh SEE ALSO
 127 .Xr cap_enter 2 ,
 128 .Xr rights 4