lib/libposix1e/cap_from_text.3

   1 .\"-
   2 .\" Copyright (c) 2000 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 18, 2000
  29 .Dt CAP_FROM_TEXT 3
  30 .Os FreeBSD 5.0
  31 .Sh NAME
  32 .Nm cap_from_text
  33 .Nd Convert Text to a Capability State in Working Store
  34 .Sh LIBRARY
  35 .Lb libposix1e
  36 .Sh SYNOPSIS
  37 .Fd #include <sys/types.h>
  38 .Fd #include <sys/capability.h>
  39 .Ft cap_t
  40 .Fn cap_from_text "const char *buf_p"
  41 .Sh DESCRIPTION
  42 This function allocates and initializes a capability state in working
  43 storage.
  44 It then sets the contents of this newly created capability state to the
  45 state represented by the human-readable, null terminated character string
  46 pointed to by
  47 .Va buf_p .
  48 .Pp
  49 This function may cause memory to be allocated.
  50 The caller should free any releasable memory, when the capability state in
  51 working storage is no longer required, by calling
  52 .Xr cap_free 3
  53 with the
  54 .Va (void *)cap_t
  55 as an argument.
  56 .Sh IMPLEMENTATION NOTES
  57 FreeBSD's support for POSIX.1e interfaces and features is still under
  58 development at this time.
  59 .Sh RETURN VALUES
  60 Upon successful completion, the function returns a pointer to the
  61 internal representation of the capability in working storage.
  62 Otherwise, a value of
  63 .Va (cap_t)NULL
  64 is returned, and
  65 .Va errno
  66 is set to indicate the error.
  67 .Sh ERRORS
  68 If any of the following conditions occur, the
  69 .Fn cap_from_text
  70 function shall return a value of
  71 .Va (cap_t)NULL
  72 and set
  73 .Va errno
  74 to the corresponding value:
  75 .Bl -tag -width Er
  76 .It Bq Er EINVAL
  77 The
  78 .Va buf_p
  79 argument does not refer to a character string, the string pointed to by
  80 .Va buf_p
  81 is not parseable by the function, the text string contains a
  82 capability name or a flag character that the implementation does not
  83 recognize as valid.
  84 .It Bq Er ENOMEM
  85 The capability state to be returned requires more memory than is allowed
  86 by the hardware or system-imposed memory management constraints.
  87 .El
  88 .Sh SEE ALSO
  89 .Xr cap 3 ,
  90 .Xr cap_free 3 ,
  91 .Xr cap_init 3 ,
  92 .Xr cap_set_flag 3 ,
  93 .Xr cap_to_text 3 ,
  94 .Xr posix1e 3
  95 .Sh STANDARDS
  96 POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
  97 of the draft continues on the cross-platform POSIX.1e implementation
  98 mailing list.  To join this list, see the
  99 .Fx
 100 POSIX.1e implementation
 101 page for more information.
 102 .Sh HISTORY
 103 POSIX.1e support was introduced in
 104 .Fx 4.0 ,
 105 and development continues.
 106 .Sh AUTHORS
 107 .An Robert N M Watson