posix1e.txt

   1 Help on module posix1e:
   2
   3 NAME
   4     posix1e - POSIX.1e ACLs manipulation
   5
   6 FILE
   7     /home/iusty/work/pylibacl/build/lib.linux-x86_64-2.4/posix1e.so
   8
   9 DESCRIPTION
  10     This module provides support for manipulating POSIX.1e ACLS
  11
  12     Depending on the operating system support for POSIX.1e,
  13     the ACL type will have more or less capabilities:
  14       - level 1, only basic support, you can create
  15         ACLs from files and text descriptions;
  16         once created, the type is immutable
  17       - level 2, complete support, you can alter
  18         the ACL once it is created
  19
  20     Also, in level 2, more types are available, corresponding
  21     to acl_entry_t (Entry type), acl_permset_t (Permset type).
  22
  23     Example:
  24     >>> import posix1e
  25     >>> acl1 = posix1e.ACL(file="file.txt")
  26     >>> print acl1
  27     user::rw-
  28     group::rw-
  29     other::r--
  30
  31     >>> b = posix1e.ACL(text="u::rx,g::-,o::-")
  32     >>> print b
  33     user::r-x
  34     group::---
  35     other::---
  36
  37     >>> b.applyto("file.txt")
  38     >>> print posix1e.ACL(file="file.txt")
  39     user::r-x
  40     group::---
  41     other::---
  42
  43     >>>
  44
  45 CLASSES
  46     __builtin__.object
  47         ACL
  48         Entry
  49         Permset
  50
  51     class ACL(__builtin__.object)
  52      |  Type which represents a POSIX ACL
  53      |
  54      |  Parameters:
  55      |    Only one keword parameter should be provided:
  56      |    - file="...", meaning create ACL representing
  57      |      the access ACL of that file
  58      |    - filedef="...", meaning create ACL representing
  59      |      the default ACL of that directory
  60      |    - fd=<int>, meaning create ACL representing
  61      |      the access ACL of that file descriptor
  62      |    - text="...", meaning create ACL from a
  63      |      textual description
  64      |    - acl=<ACL instance>, meaning create a copy
  65      |      of an existing ACL instance
  66      |    - mode=<int>, meaning create an ACL from a numeric mode
  67      |      (e.g. mode=0644) (this is valid only when the C library
  68      |      provides the acl_from_mode call)
  69      |  If no parameters are passed, create an empty ACL; this
  70      |  makes sense only when your OS supports ACL modification
  71      |   (i.e. it implements full POSIX.1e support)
  72      |
  73      |  Methods defined here:
  74      |
  75      |  __cmp__(...)
  76      |      x.__cmp__(y) <==> cmp(x,y)
  77      |
  78      |  __eq__(...)
  79      |      x.__eq__(y) <==> x==y
  80      |
  81      |  __ge__(...)
  82      |      x.__ge__(y) <==> x>=y
  83      |
  84      |  __getstate__(...)
  85      |      Dumps the ACL to an external format.
  86      |
  87      |  __gt__(...)
  88      |      x.__gt__(y) <==> x>y
  89      |
  90      |  __init__(...)
  91      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  92      |
  93      |  __iter__(...)
  94      |      x.__iter__() <==> iter(x)
  95      |
  96      |  __le__(...)
  97      |      x.__le__(y) <==> x<=y
  98      |
  99      |  __lt__(...)
 100      |      x.__lt__(y) <==> x<y
 101      |
 102      |  __ne__(...)
 103      |      x.__ne__(y) <==> x!=y
 104      |
 105      |  __setstate__(...)
 106      |      Loads the ACL from an external format.
 107      |
 108      |  __str__(...)
 109      |      x.__str__() <==> str(x)
 110      |
 111      |  append(...)
 112      |      Append a new Entry to the ACL and return it.
 113      |
 114      |      This is a convenience function to create a new Entry
 115      |      and append it to the ACL.
 116      |      If a parameter of type Entry instance is given, the
 117      |      entry will be a copy of that one (as if copied with
 118      |      Entry.copy()), otherwise, the new entry will be empty.
 119      |
 120      |  applyto(...)
 121      |      Apply the ACL to a file or filehandle.
 122      |
 123      |      Parameters:
 124      |        - either a filename or a file-like object or an integer; this
 125      |          represents the filesystem object on which to act
 126      |        - optional flag representing the type of ACL to set, either
 127      |          ACL_TYPE_ACCESS (default) or ACL_TYPE_DEFAULT
 128      |
 129      |  calc_mask(...)
 130      |      Compute the file group class mask.
 131      |
 132      |      The calc_mask() method calculates and sets the permissions
 133      |      associated with the ACL_MASK Entry of the ACL.
 134      |      The value of the new permissions is the union of the permissions
 135      |      granted by all entries of tag type ACL_GROUP, ACL_GROUP_OBJ, or
 136      |      ACL_USER.  If the ACL already contains an ACL_MASK entry, its
 137      |      permissions are overwritten; if it does not contain an ACL_MASK
 138      |      Entry, one is added.
 139      |
 140      |      The order of existing entries in the ACL is undefined after this
 141      |      function.
 142      |
 143      |  check(...)
 144      |      Check the ACL validity.
 145      |
 146      |      This is a non-portable, Linux specific extension that allow more
 147      |      information to be retrieved in case an ACL is not valid than the
 148      |      validate() method.
 149      |
 150      |      This method will return either False (the ACL is valid), or a tuple
 151      |      with two elements. The first element is one of the following
 152      |      constants:
 153      |        - ACL_MULTI_ERROR: The ACL contains multiple entries that have a
 154      |                           tag type that may occur at most once
 155      |        - ACL_DUPLICATE_ERROR: The ACL contains multiple ACL_USER or
 156      |                               ACL_GROUP entries  with the same ID
 157      |        - ACL_MISS_ERROR: A required entry is missing
 158      |        - ACL_ENTRY_ERROR: The ACL contains an invalid entry tag type
 159      |
 160      |      The second element of the tuple is the index of the entry that is
 161      |      invalid (in the same order as by iterating over the ACL entry)
 162      |
 163      |  delete_entry(...)
 164      |      Deletes an entry from the ACL.
 165      |
 166      |      Note: Only with level 2
 167      |      Parameters:
 168      |       - the Entry object which should be deleted; note that after
 169      |         this function is called, that object is unusable any longer
 170      |         and should be deleted
 171      |
 172      |  next(...)
 173      |      x.next() -> the next value, or raise StopIteration
 174      |
 175      |  to_any_text(...)
 176      |      Convert the ACL to a custom text format.
 177      |
 178      |      This method encapsulates the acl_to_any_text function. It allows a
 179      |      customized text format to be generated for the ACL. See
 180      |      acl_to_any_text(3) for more details.
 181      |
 182      |      Parameters:
 183      |        - prefix: if given, this string will be prepended to all lines
 184      |        - separator: a single character (defaults to '\n'); this will be
 185      |                     user to separate the entries in the ACL
 186      |        - options: a bitwise combination of:
 187      |            TEXT_ABBREVIATE: use 'u' instead of 'user', 'g' instead of
 188      |                             'group', etc.
 189      |            TEXT_NUMERIC_IDS: User and group IDs are included as decimal
 190      |                              numbers instead of names
 191      |            TEXT_SOME_EFFECTIVE: Include comments denoting the effective
 192      |                                 permissions when some are masked
 193      |            TEXT_ALL_EFFECTIVE: Include comments after all ACL entries
 194      |                                affected by an ACL_MASK entry
 195      |            TEXT_SMART_INDENT: Used in combination with the _EFFECTIVE
 196      |                               options, this will ensure that comments
 197      |                               are alligned to the fourth tab position
 198      |                               (assuming one tab equal eight spaces
 199      |
 200      |  valid(...)
 201      |      Test the ACL for validity.
 202      |
 203      |      This method tests the ACL to see if it is a valid ACL
 204      |      in terms of the filesystem. More precisely, it checks that:
 205      |
 206      |      The ACL contains exactly one entry with each of the
 207      |      ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries
 208      |      with ACL_USER and ACL_GROUP tag types may appear zero or more
 209      |      times in an ACL. An ACL that contains entries of ACL_USER or
 210      |      ACL_GROUP tag types must contain exactly one entry of the
 211      |      ACL_MASK tag type. If an ACL contains no entries of
 212      |      ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.
 213      |
 214      |      All user ID qualifiers must be unique among all entries of
 215      |      the ACL_USER tag type, and all group IDs must be unique among all
 216      |      entries of ACL_GROUP tag type.
 217      |
 218      |      The method will return 1 for a valid ACL and 0 for an invalid one.
 219      |      This has been chosen because the specification for acl_valid in
 220      |      the POSIX.1e standard documents only one possible value for errno
 221      |      in case of an invalid ACL, so we can't differentiate between
 222      |      classes of errors. Other suggestions are welcome.
 223      |
 224      |  ----------------------------------------------------------------------
 225      |  Data and other attributes defined here:
 226      |
 227      |  __new__ = <built-in method __new__ of type object>
 228      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 229
 230     class Entry(__builtin__.object)
 231      |  Type which represents an entry in an ACL.
 232      |
 233      |  The type exists only if the OS has full support for POSIX.1e
 234      |  Can be created either by:
 235      |    e = posix1e.Entry(myACL) # this creates a new entry in the ACL
 236      |  or by:
 237      |    for entry in myACL:
 238      |        print entry
 239      |
 240      |  Note that the Entry keeps a reference to its ACL, so even if
 241      |  you delete the ACL, it won't be cleaned up and will continue to
 242      |  exist until its Entry(ies) will be deleted.
 243      |
 244      |  Methods defined here:
 245      |
 246      |  __init__(...)
 247      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 248      |
 249      |  __str__(...)
 250      |      x.__str__() <==> str(x)
 251      |
 252      |  copy(...)
 253      |      Copy an ACL entry.
 254      |
 255      |      This method sets all the parameters to those of another
 256      |      entry, even one of another's ACL
 257      |      Parameters:
 258      |       - src, instance of type Entry
 259      |
 260      |  ----------------------------------------------------------------------
 261      |  Data and other attributes defined here:
 262      |
 263      |  __new__ = <built-in method __new__ of type object>
 264      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 265      |
 266      |  parent = <attribute 'parent' of 'posix1e.Entry' objects>
 267      |      The parent ACL of this entry
 268      |
 269      |  permset = <attribute 'permset' of 'posix1e.Entry' objects>
 270      |      The permission set of this ACL entry
 271      |
 272      |  qualifier = <attribute 'qualifier' of 'posix1e.Entry' objects>
 273      |      The qualifier of the current entry
 274      |
 275      |      If the tag type is ACL_USER, this should be a user id.
 276      |      If the tag type if ACL_GROUP, this should be a group id.
 277      |      Else, it doesn't matter.
 278      |
 279      |  tag_type = <attribute 'tag_type' of 'posix1e.Entry' objects>
 280      |      The tag type of the current entry
 281      |
 282      |      This is one of:
 283      |       - ACL_UNDEFINED_TAG
 284      |       - ACL_USER_OBJ
 285      |       - ACL_USER
 286      |       - ACL_GROUP_OBJ
 287      |       - ACL_GROUP
 288      |       - ACL_MASK
 289      |       - ACL_OTHER
 290
 291     class Permset(__builtin__.object)
 292      |  Type which represents the permission set in an ACL entry
 293      |
 294      |  The type exists only if the OS has full support for POSIX.1e
 295      |  Can be created either by:
 296      |    perms = myEntry.permset
 297      |  or by:
 298      |    perms = posix1e.Permset(myEntry)
 299      |
 300      |  Note that the Permset keeps a reference to its Entry, so even if
 301      |  you delete the entry, it won't be cleaned up and will continue to
 302      |  exist until its Permset will be deleted.
 303      |
 304      |  Methods defined here:
 305      |
 306      |  __init__(...)
 307      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 308      |
 309      |  __str__(...)
 310      |      x.__str__() <==> str(x)
 311      |
 312      |  add(...)
 313      |      Add a permission to the permission set.
 314      |
 315      |      The add() function adds the permission contained in
 316      |      the argument perm to the permission set.  An attempt
 317      |      to add a permission that is already contained in the
 318      |      permission set is not considered an error.
 319      |      Parameters:
 320      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 321      |      Return value:
 322      |        None
 323      |      Can raise: IOError
 324      |
 325      |  clear(...)
 326      |      Clear all permissions from the permission set.
 327      |
 328      |  delete(...)
 329      |      Delete a permission from the permission set.
 330      |
 331      |      The delete() function deletes the permission contained in
 332      |      the argument perm from the permission set.  An attempt
 333      |      to delete a permission that is not contained in the
 334      |      permission set is not considered an error.
 335      |      Parameters:
 336      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 337      |      Return value:
 338      |        None
 339      |      Can raise: IOError
 340      |
 341      |  test(...)
 342      |      Test if a permission exists in the permission set.
 343      |
 344      |      The test() function tests if the permission contained in
 345      |      the argument perm exits the permission set.
 346      |      Parameters:
 347      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 348      |      Return value:
 349      |        Bool
 350      |      Can raise: IOError
 351      |
 352      |  ----------------------------------------------------------------------
 353      |  Data and other attributes defined here:
 354      |
 355      |  __new__ = <built-in method __new__ of type object>
 356      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 357      |
 358      |  execute = <attribute 'execute' of 'posix1e.Permset' objects>
 359      |      Execute permsission
 360      |
 361      |      This is a convenience method of access; the
 362      |      same effect can be achieved using the functions
 363      |      add(), test(), delete(), and those can take any
 364      |      permission defined by your platform.
 365      |
 366      |  read = <attribute 'read' of 'posix1e.Permset' objects>
 367      |      Read permsission
 368      |
 369      |      This is a convenience method of access; the
 370      |      same effect can be achieved using the functions
 371      |      add(), test(), delete(), and those can take any
 372      |      permission defined by your platform.
 373      |
 374      |  write = <attribute 'write' of 'posix1e.Permset' objects>
 375      |      Write permsission
 376      |
 377      |      This is a convenience method of access; the
 378      |      same effect can be achieved using the functions
 379      |      add(), test(), delete(), and those can take any
 380      |      permission defined by your platform.
 381
 382 FUNCTIONS
 383     delete_default(...)
 384         Delete the default ACL from a directory.
 385
 386         This function deletes the default ACL associated with
 387         a directory (the ACL which will be ANDed with the mode
 388         parameter to the open, creat functions).
 389         Parameters:
 390           - a string representing the directory whose default ACL
 391             should be deleted
 392
 393 DATA
 394     ACL_DUPLICATE_ERROR = 8192
 395     ACL_ENTRY_ERROR = 16384
 396     ACL_EXECUTE = 1
 397     ACL_GROUP = 8
 398     ACL_GROUP_OBJ = 4
 399     ACL_MASK = 16
 400     ACL_MISS_ERROR = 12288
 401     ACL_MULTI_ERROR = 4096
 402     ACL_OTHER = 32
 403     ACL_READ = 4
 404     ACL_TYPE_ACCESS = 32768
 405     ACL_TYPE_DEFAULT = 16384
 406     ACL_UNDEFINED_TAG = 0
 407     ACL_USER = 2
 408     ACL_USER_OBJ = 1
 409     ACL_WRITE = 2
 410     TEXT_ABBREVIATE = 16
 411     TEXT_ALL_EFFECTIVE = 2
 412     TEXT_NUMERIC_IDS = 8
 413     TEXT_SMART_INDENT = 4
 414     TEXT_SOME_EFFECTIVE = 1
 415
 416