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