posix1e.txt

   1 Python Library Documentation: module posix1e
   2
   3 NAME
   4     posix1e - POSIX.1e ACLs manipulation
   5
   6 FILE
   7     /home/iusty/work/pylibacl/build/lib.linux-i686-2.2/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      |  If no parameters are passed, create an empty ACL; this
  67      |  makes sense only when your OS supports ACL modification
  68      |   (i.e. it implements full POSIX.1e support)
  69      |
  70      |  Methods defined here:
  71      |
  72      |  __getstate__(...)
  73      |      Dumps the ACL to an external format.
  74      |
  75      |  __init__(...)
  76      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
  77      |
  78      |  __iter__(...)
  79      |      x.__iter__() <==> iter(x)
  80      |
  81      |  __setstate__(...)
  82      |      Loads the ACL from an external format.
  83      |
  84      |  __str__(...)
  85      |      x.__str__() <==> str(x)
  86      |
  87      |  append(...)
  88      |      Append a new Entry to the ACL and return it.
  89      |
  90      |      This is a convenience function to create a new Entry
  91      |      and append it to the ACL.
  92      |      If a parameter of type Entry instance is given, the
  93      |      entry will be a copy of that one (as if copied with
  94      |      Entry.copy()), otherwise, the new entry will be empty.
  95      |
  96      |  applyto(...)
  97      |      Apply the ACL to a file or filehandle.
  98      |
  99      |      Parameters:
 100      |        - either a filename or a file-like object or an integer; this
 101      |          represents the filesystem object on which to act
 102      |        - optional flag representing the type of ACL to set, either
 103      |          ACL_TYPE_ACCESS (default) or ACL_TYPE_DEFAULT
 104      |
 105      |  calc_mask(...)
 106      |      Compute the file group class mask.
 107      |
 108      |      The calc_mask() method calculates and sets the permissions
 109      |      associated with the ACL_MASK Entry of the ACL.
 110      |      The value of the new permissions is the union of the permissions
 111      |      granted by all entries of tag type ACL_GROUP, ACL_GROUP_OBJ, or
 112      |      ACL_USER.  If the ACL already contains an ACL_MASK entry, its
 113      |      permissions are overwritten; if it does not contain an ACL_MASK
 114      |      Entry, one is added.
 115      |
 116      |      The order of existing entries in the ACL is undefined after this
 117      |      function.
 118      |
 119      |  delete_entry(...)
 120      |      Deletes an entry from the ACL.
 121      |
 122      |      Note: Only with level 2
 123      |      Parameters:
 124      |       - the Entry object which should be deleted; note that after
 125      |         this function is called, that object is unusable any longer
 126      |         and should be deleted
 127      |
 128      |  next(...)
 129      |      x.next() -> the next value, or raise StopIteration
 130      |
 131      |  valid(...)
 132      |      Test the ACL for validity.
 133      |
 134      |      This method tests the ACL to see if it is a valid ACL
 135      |      in terms of the filesystem. More precisely, it checks:
 136      |      A valid ACL contains exactly one entry with each of the ACL_USER_OBJ,
 137      |      ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and
 138      |      ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that
 139      |      contains entries of ACL_USER or ACL_GROUP tag types must contain exactly
 140      |      one entry of the ACL_MASK tag type. If an ACL contains no entries of
 141      |      ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.
 142      |
 143      |      All user ID qualifiers must be unique among all entries of ACL_USER tag
 144      |      type, and all group IDs must be unique among all entries of ACL_GROUP tag
 145      |      type.
 146      |
 147      |      The method will return 1 for a valid ACL and 0 for an invalid one.
 148      |      This has been chosen because the specification for acl_valid in POSIX.1e
 149      |      documents only one possible value for errno in case of an invalid ACL,
 150      |      so we can't differentiate between classes of errors. Other suggestions
 151      |      are welcome.
 152      |
 153      |  ----------------------------------------------------------------------
 154      |  Data and non-method functions defined here:
 155      |
 156      |  __doc__ = 'Type which represents a POSIX ACL\n\nParameters:\n ...tion\...
 157      |      str(object) -> string
 158      |
 159      |      Return a nice string representation of the object.
 160      |      If the argument is a string, the return value is the same object.
 161      |
 162      |  __new__ = <built-in method __new__ of type object>
 163      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 164      |
 165      |  ----------------------------------------------------------------------
 166      |  Methods inherited from __builtin__.object:
 167      |
 168      |  __delattr__(...)
 169      |      x.__delattr__('name') <==> del x.name
 170      |
 171      |  __getattribute__(...)
 172      |      x.__getattribute__('name') <==> x.name
 173      |
 174      |  __hash__(...)
 175      |      x.__hash__() <==> hash(x)
 176      |
 177      |  __reduce__(...)
 178      |      helper for pickle
 179      |
 180      |  __repr__(...)
 181      |      x.__repr__() <==> repr(x)
 182      |
 183      |  __setattr__(...)
 184      |      x.__setattr__('name', value) <==> x.name = value
 185      |
 186      |  ----------------------------------------------------------------------
 187      |  Data and non-method functions inherited from __builtin__.object:
 188      |
 189      |  __class__ = <type 'type'>
 190      |      the object's class
 191
 192     class Entry(__builtin__.object)
 193      |  Type which represents an entry in an ACL.
 194      |
 195      |  The type exists only if the OS has full support for POSIX.1e
 196      |  Can be created either by:
 197      |    e = posix1e.Entry(myACL) # this creates a new entry in the ACL
 198      |  or by:
 199      |    for entry in myACL:
 200      |        print entry
 201      |
 202      |  Note that the Entry keeps a reference to its ACL, so even if
 203      |  you delete the ACL, it won't be cleaned up and will continue to
 204      |  exist until its Entry(ies) will be deleted.
 205      |
 206      |  Methods defined here:
 207      |
 208      |  __init__(...)
 209      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 210      |
 211      |  __str__(...)
 212      |      x.__str__() <==> str(x)
 213      |
 214      |  copy(...)
 215      |      Copy an ACL entry.
 216      |
 217      |      This method sets all the parameters to those of another
 218      |      entry, even one of another's ACL
 219      |      Parameters:
 220      |       - src, instance of type Entry
 221      |
 222      |  ----------------------------------------------------------------------
 223      |  Data and non-method functions defined here:
 224      |
 225      |  __doc__ = 'Type which represents an entry in an ACL.\n\nThe t... to \n...
 226      |      str(object) -> string
 227      |
 228      |      Return a nice string representation of the object.
 229      |      If the argument is a string, the return value is the same object.
 230      |
 231      |  __new__ = <built-in method __new__ of type object>
 232      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 233      |
 234      |  parent = <attribute 'parent' of 'posix1e.Entry' objects>
 235      |      The parent ACL of this entry
 236      |
 237      |
 238      |  permset = <attribute 'permset' of 'posix1e.Entry' objects>
 239      |      The permission set of this ACL entry
 240      |
 241      |
 242      |  qualifier = <attribute 'qualifier' of 'posix1e.Entry' objects>
 243      |      The qualifier of the current entry
 244      |
 245      |      If the tag type is ACL_USER, this should be a user id.
 246      |      If the tag type if ACL_GROUP, this should be a group id.
 247      |      Else, it doesn't matter.
 248      |
 249      |
 250      |  tag_type = <attribute 'tag_type' of 'posix1e.Entry' objects>
 251      |      The tag type of the current entry
 252      |
 253      |      This is one of:
 254      |       - ACL_UNDEFINED_TAG
 255      |       - ACL_USER_OBJ
 256      |       - ACL_USER
 257      |       - ACL_GROUP_OBJ
 258      |       - ACL_GROUP
 259      |       - ACL_MASK
 260      |       - ACL_OTHER
 261      |
 262      |
 263      |  ----------------------------------------------------------------------
 264      |  Methods inherited from __builtin__.object:
 265      |
 266      |  __delattr__(...)
 267      |      x.__delattr__('name') <==> del x.name
 268      |
 269      |  __getattribute__(...)
 270      |      x.__getattribute__('name') <==> x.name
 271      |
 272      |  __hash__(...)
 273      |      x.__hash__() <==> hash(x)
 274      |
 275      |  __reduce__(...)
 276      |      helper for pickle
 277      |
 278      |  __repr__(...)
 279      |      x.__repr__() <==> repr(x)
 280      |
 281      |  __setattr__(...)
 282      |      x.__setattr__('name', value) <==> x.name = value
 283      |
 284      |  ----------------------------------------------------------------------
 285      |  Data and non-method functions inherited from __builtin__.object:
 286      |
 287      |  __class__ = <type 'type'>
 288      |      the object's class
 289
 290     class Permset(__builtin__.object)
 291      |  Type which represents the permission set in an ACL entry
 292      |
 293      |  The type exists only if the OS has full support for POSIX.1e
 294      |  Can be created either by:
 295      |    perms = myEntry.permset
 296      |  or by:
 297      |    perms = posix1e.Permset(myEntry)
 298      |
 299      |  Note that the Permset keeps a reference to its Entry, so even if
 300      |  you delete the entry, it won't be cleaned up and will continue to
 301      |  exist until its Permset will be deleted.
 302      |
 303      |  Methods defined here:
 304      |
 305      |  __init__(...)
 306      |      x.__init__(...) initializes x; see x.__class__.__doc__ for signature
 307      |
 308      |  __str__(...)
 309      |      x.__str__() <==> str(x)
 310      |
 311      |  add(...)
 312      |      Add a permission to the permission set.
 313      |
 314      |      The add() function adds the permission contained in
 315      |      the argument perm to the permission set.  An attempt
 316      |      to add a permission that is already contained in the
 317      |      permission set is not considered an error.
 318      |      Parameters:
 319      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 320      |      Return value:
 321      |        None
 322      |      Can raise: IOError
 323      |
 324      |  clear(...)
 325      |      Clear all permissions from the permission set.
 326      |
 327      |  delete(...)
 328      |      Delete a permission from the permission set.
 329      |
 330      |      The delete() function deletes the permission contained in
 331      |      the argument perm from the permission set.  An attempt
 332      |      to delete a permission that is not contained in the
 333      |      permission set is not considered an error.
 334      |      Parameters:
 335      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 336      |      Return value:
 337      |        None
 338      |      Can raise: IOError
 339      |
 340      |  test(...)
 341      |      Test if a permission exists in the permission set.
 342      |
 343      |      The test() function tests if the permission contained in
 344      |      the argument perm exits the permission set.
 345      |      Parameters:
 346      |        - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
 347      |      Return value:
 348      |        Bool
 349      |      Can raise: IOError
 350      |
 351      |  ----------------------------------------------------------------------
 352      |  Data and non-method functions defined here:
 353      |
 354      |  __doc__ = 'Type which represents the permission set in an A...nue to \...
 355      |      str(object) -> string
 356      |
 357      |      Return a nice string representation of the object.
 358      |      If the argument is a string, the return value is the same object.
 359      |
 360      |  __new__ = <built-in method __new__ of type object>
 361      |      T.__new__(S, ...) -> a new object with type S, a subtype of T
 362      |
 363      |  execute = <attribute 'execute' of 'posix1e.Permset' objects>
 364      |      Execute permsission
 365      |
 366      |      This is a convenience method of access; the
 367      |      same effect can be achieved using the functions
 368      |      add(), test(), delete(), and those can take any
 369      |      permission defined by your platform.
 370      |
 371      |
 372      |  read = <attribute 'read' of 'posix1e.Permset' objects>
 373      |      Read permsission
 374      |
 375      |      This is a convenience method of access; the
 376      |      same effect can be achieved using the functions
 377      |      add(), test(), delete(), and those can take any
 378      |      permission defined by your platform.
 379      |
 380      |
 381      |  write = <attribute 'write' of 'posix1e.Permset' objects>
 382      |      Write permsission
 383      |
 384      |      This is a convenience method of access; the
 385      |      same effect can be achieved using the functions
 386      |      add(), test(), delete(), and those can take any
 387      |      permission defined by your platform.
 388      |
 389      |
 390      |  ----------------------------------------------------------------------
 391      |  Methods inherited from __builtin__.object:
 392      |
 393      |  __delattr__(...)
 394      |      x.__delattr__('name') <==> del x.name
 395      |
 396      |  __getattribute__(...)
 397      |      x.__getattribute__('name') <==> x.name
 398      |
 399      |  __hash__(...)
 400      |      x.__hash__() <==> hash(x)
 401      |
 402      |  __reduce__(...)
 403      |      helper for pickle
 404      |
 405      |  __repr__(...)
 406      |      x.__repr__() <==> repr(x)
 407      |
 408      |  __setattr__(...)
 409      |      x.__setattr__('name', value) <==> x.name = value
 410      |
 411      |  ----------------------------------------------------------------------
 412      |  Data and non-method functions inherited from __builtin__.object:
 413      |
 414      |  __class__ = <type 'type'>
 415      |      the object's class
 416
 417 FUNCTIONS
 418     delete_default(...)
 419         Delete the default ACL from a directory.
 420
 421         This function deletes the default ACL associated with
 422         a directory (the ACL which will be ANDed with the mode
 423         parameter to the open, creat functions).
 424         Parameters:
 425           - a string representing the directory whose default ACL
 426             should be deleted
 427
 428 DATA
 429     ACL_EXECUTE = 1
 430     ACL_GROUP = 8
 431     ACL_GROUP_OBJ = 4
 432     ACL_MASK = 16
 433     ACL_OTHER = 32
 434     ACL_READ = 4
 435     ACL_TYPE_ACCESS = 32768
 436     ACL_TYPE_DEFAULT = 16384
 437     ACL_UNDEFINED_TAG = 0
 438     ACL_USER = 2
 439     ACL_USER_OBJ = 1
 440     ACL_WRITE = 2
 441     __file__ = '/home/iusty/work/pylibacl/build/lib.linux-i686-2.2/posix1e...
 442     __name__ = 'posix1e'
 443