1 Help on module posix1e:
4 posix1e - POSIX.1e ACLs manipulation
7 /home/iusty/work/pylibacl/build/lib.linux-x86_64-2.4/posix1e.so
10 This module provides support for manipulating POSIX.1e ACLS
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
20 Also, in level 2, more types are available, corresponding
21 to acl_entry_t (Entry type), acl_permset_t (Permset type).
25 >>> acl1 = posix1e.ACL(file="file.txt")
31 >>> b = posix1e.ACL(text="u::rx,g::-,o::-")
37 >>> b.applyto("file.txt")
38 >>> print posix1e.ACL(file="file.txt")
51 class ACL(__builtin__.object)
52 | Type which represents a POSIX ACL
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
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)
73 | Methods defined here:
76 | x.__cmp__(y) <==> cmp(x,y)
79 | x.__eq__(y) <==> x==y
82 | x.__ge__(y) <==> x>=y
85 | Dumps the ACL to an external format.
88 | x.__gt__(y) <==> x>y
91 | x.__init__(...) initializes x; see x.__class__.__doc__ for signature
94 | x.__iter__() <==> iter(x)
97 | x.__le__(y) <==> x<=y
100 | x.__lt__(y) <==> x<y
103 | x.__ne__(y) <==> x!=y
106 | Loads the ACL from an external format.
109 | x.__str__() <==> str(x)
112 | Append a new Entry to the ACL and return it.
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.
121 | Apply the ACL to a file or filehandle.
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
130 | Compute the file group class mask.
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.
140 | The order of existing entries in the ACL is undefined after this
144 | Check the ACL validity.
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
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
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
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)
164 | Deletes an entry from the ACL.
166 | Note: Only with level 2
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
173 | x.next() -> the next value, or raise StopIteration
176 | Convert the ACL to a custom text format.
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.
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
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
201 | Test the ACL for validity.
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:
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.
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.
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.
224 | ----------------------------------------------------------------------
225 | Data and other attributes defined here:
227 | __new__ = <built-in method __new__ of type object>
228 | T.__new__(S, ...) -> a new object with type S, a subtype of T
230 class Entry(__builtin__.object)
231 | Type which represents an entry in an ACL.
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
237 | for entry in myACL:
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.
244 | Methods defined here:
247 | x.__init__(...) initializes x; see x.__class__.__doc__ for signature
250 | x.__str__() <==> str(x)
255 | This method sets all the parameters to those of another
256 | entry, even one of another's ACL
258 | - src, instance of type Entry
260 | ----------------------------------------------------------------------
261 | Data and other attributes defined here:
263 | __new__ = <built-in method __new__ of type object>
264 | T.__new__(S, ...) -> a new object with type S, a subtype of T
266 | parent = <attribute 'parent' of 'posix1e.Entry' objects>
267 | The parent ACL of this entry
269 | permset = <attribute 'permset' of 'posix1e.Entry' objects>
270 | The permission set of this ACL entry
272 | qualifier = <attribute 'qualifier' of 'posix1e.Entry' objects>
273 | The qualifier of the current entry
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.
279 | tag_type = <attribute 'tag_type' of 'posix1e.Entry' objects>
280 | The tag type of the current entry
283 | - ACL_UNDEFINED_TAG
291 class Permset(__builtin__.object)
292 | Type which represents the permission set in an ACL entry
294 | The type exists only if the OS has full support for POSIX.1e
295 | Can be created either by:
296 | perms = myEntry.permset
298 | perms = posix1e.Permset(myEntry)
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.
304 | Methods defined here:
307 | x.__init__(...) initializes x; see x.__class__.__doc__ for signature
310 | x.__str__() <==> str(x)
313 | Add a permission to the permission set.
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.
320 | - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
326 | Clear all permissions from the permission set.
329 | Delete a permission from the permission set.
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.
336 | - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
342 | Test if a permission exists in the permission set.
344 | The test() function tests if the permission contained in
345 | the argument perm exits the permission set.
347 | - perm a permission (ACL_WRITE, ACL_READ, ACL_EXECUTE, ...
352 | ----------------------------------------------------------------------
353 | Data and other attributes defined here:
355 | __new__ = <built-in method __new__ of type object>
356 | T.__new__(S, ...) -> a new object with type S, a subtype of T
358 | execute = <attribute 'execute' of 'posix1e.Permset' objects>
359 | Execute permsission
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.
366 | read = <attribute 'read' of 'posix1e.Permset' objects>
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.
374 | write = <attribute 'write' of 'posix1e.Permset' objects>
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.
384 Delete the default ACL from a directory.
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).
390 - a string representing the directory whose default ACL
394 ACL_DUPLICATE_ERROR = 8192
395 ACL_ENTRY_ERROR = 16384
400 ACL_MISS_ERROR = 12288
401 ACL_MULTI_ERROR = 4096
404 ACL_TYPE_ACCESS = 32768
405 ACL_TYPE_DEFAULT = 16384
406 ACL_UNDEFINED_TAG = 0
411 TEXT_ALL_EFFECTIVE = 2
413 TEXT_SMART_INDENT = 4
414 TEXT_SOME_EFFECTIVE = 1