]> git.k1024.org Git - debian-pyxattr.git/blob - xattr.txt
Imported Debian patch 0.2.2-1
[debian-pyxattr.git] / xattr.txt
1 Help on module xattr:
2
3 NAME
4     xattr - Access extended filesystem attributes
5
6 FILE
7     /home/iusty/work/pyxattr/build/lib.linux-i686-2.3/xattr.so
8
9 DESCRIPTION
10     This module gives access to the extended attributes present
11     in some operating systems/filesystems. You can list attributes,
12     get, set and remove them.
13     The last and optional parameter for all functions is a boolean 
14     value which enables the 'l-' version of the functions - acting
15     on symbolic links and not their destination.
16     
17     Example: 
18     >>> import xattr
19     >>> xattr.listxattr("file.txt")
20     ('user.mime_type',)
21     >>> xattr.getxattr("file.txt", "user.mime_type")
22     'text/plain'
23     >>> xattr.setxattr("file.txt", "user.comment", "Simple text file")
24     >>> xattr.listxattr("file.txt")
25     ('user.mime_type', 'user.comment')
26     >>> xattr.removexattr ("file.txt", "user.comment")
27
28 FUNCTIONS
29     getxattr(...)
30         Get the value of a given extended attribute.
31         
32         Parameters:
33                 - a string representing filename, or a file-like object,
34                       or a file descriptor; this represents the file on 
35                       which to act
36                 - a string, representing the attribute whose value to retrieve;
37                       usually in form of system.posix_acl or user.mime_type
38                 - (optional) a boolean value (defaults to false), which, if
39                       the file name given is a symbolic link, makes the
40                       function operate on the symbolic link itself instead
41                       of its target;
42     
43     listxattr(...)
44         Return the tuple of attribute names from a file
45         
46         Parameters:
47                 - a string representing filename, or a file-like object,
48                       or a file descriptor; this represents the file to 
49                       be queried
50                 - (optional) a boolean value (defaults to false), which, if
51                       the file name given is a symbolic link, makes the
52                       function operate on the symbolic link itself instead
53                       of its target;
54     
55     removexattr(...)
56         Remove an attribute from a file
57         
58         Parameters:
59                 - a string representing filename, or a file-like object,
60                       or a file descriptor; this represents the file on 
61                       which to act
62                 - a string, representing the attribute to be removed;
63                       usually in form of system.posix_acl or user.mime_type
64                 - (optional) a boolean value (defaults to false), which, if
65                       the file name given is a symbolic link, makes the
66                       function operate on the symbolic link itself instead
67                       of its target;
68     
69     setxattr(...)
70         Set the value of a given extended attribute.
71         Be carefull in case you want to set attributes on symbolic
72         links, you have to use all the 5 parameters; use 0 for the 
73         flags value if you want the default behavior (create or replace)
74         
75         Parameters:
76                 - a string representing filename, or a file-like object,
77                       or a file descriptor; this represents the file on 
78                       which to act
79                 - a string, representing the attribute whose value to set;
80                       usually in form of system.posix_acl or user.mime_type
81                 - a string, possibly with embedded NULLs; note that there
82                       are restrictions regarding the size of the value, for
83                       example, for ext2/ext3, maximum size is the block size
84                 - (optional) flags; if 0 or ommited the attribute will be 
85                       created or replaced; if XATTR_CREATE, the attribute 
86                       will be created, giving an error if it already exists;
87                       of XATTR_REPLACE, the attribute will be replaced,
88                       giving an error if it doesn't exists;
89                 - (optional) a boolean value (defaults to false), which, if
90                       the file name given is a symbolic link, makes the
91                       function operate on the symbolic link itself instead
92                       of its target;
93
94 DATA
95     XATTR_CREATE = 1
96     XATTR_REPLACE = 2
97
98