[File-extattr-commits] File-ExtAttr/lib/File ExtAttr.pm,1.12,1.13

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/file-extattr/File-ExtAttr/lib/File
In directory sc8-pr-cvs5.sourceforge.net:/tmp/cvs-serv32007/lib/File

Modified Files:
	ExtAttr.pm 
Log Message:
Initial support for cross-platform namespacing on Linux

Index: ExtAttr.pm
===================================================================
RCS file: /cvsroot/file-extattr/File-ExtAttr/lib/File/ExtAttr.pm,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** ExtAttr.pm	15 Aug 2006 09:18:04 -0000	1.12
--- ExtAttr.pm	19 Aug 2006 14:06:25 -0000	1.13
***************
*** 11,32 ****

    # Manipulate the extended attributes of files.
!   setfattr('foo.txt', 'user.colour', 'red') || die;
!   my $colour = getfattr('bar.txt', 'user.colour');
    if (defined($colour))
    {
        print $colour;
!       delfattr('bar.txt', 'user.colour');
    }

    # Manipulate the extended attributes of a file via a file handle.
    my $fh = new IO::File('<foo.txt') || die;
!   setfattr($fh, 'user.colour', 'red') || die;

    $fh = new IO::File('<bar.txt') || die;
!   $colour = getfattr($fh, 'user.colour');
    if (defined($colour))
    {
        print $colour;
!       delfattr($fh, 'user.colour');
    }

--- 11,32 ----

    # Manipulate the extended attributes of files.
!   setfattr('foo.txt', 'colour', 'red') || die;
!   my $colour = getfattr('bar.txt', 'colour');
    if (defined($colour))
    {
        print $colour;
!       delfattr('bar.txt', 'colour');
    }

    # Manipulate the extended attributes of a file via a file handle.
    my $fh = new IO::File('<foo.txt') || die;
!   setfattr($fh, 'colour', 'red') || die;

    $fh = new IO::File('<bar.txt') || die;
!   $colour = getfattr($fh, 'colour');
    if (defined($colour))
    {
        print $colour;
!       delfattr($fh, 'colour');
    }

***************
*** 45,53 ****

  Extended attributes may also not be supported by your filesystem
! or require special options to be enabled for a particular filesystem
! (e.g. "mount -o user_xattr /dev/hda1 /some/path").

! NOTE: The API is not stable. It may change as part of supporting
! multiple operating systems.

  =cut
--- 45,108 ----

  Extended attributes may also not be supported by your filesystem
! or require special options to be enabled for a particular filesystem.
! E.g.:

!   mount -o user_xattr /dev/hda1 /some/path
! 
! =head2 Namespaces
! 
! Some implementations of extended attributes support namespacing.
! In those implementations, the attribute is referred to by namespace
! and attribute name.
! 
! =over 4
! 
! =item Linux
! 
! The primary namespaces are C<user> for user programs;
! C<security>, C<system> and C<trusted> for file security/access-control.
! See L<http://www.die.net/doc/linux/man/man5/attr.5.html>
! for more details.
! 
! Namespaces on Linux are described by a string, but only certain values
! are supported by filesystems. In general C<user>, C<security>, C<system>
! and C<trusted> are supported, by others may be supported --
! e.g.: C<os2> on JFS. File::Extattr will be able to access any of these.
! 
! =item FreeBSD, NetBSD, OpenBSD
! 
! *BSD have two namespaces: C<user> and C<system>.
! 
! Namespaces on *BSD are described by an integer. File::ExtAttr will only
! be able to access attributes in C<user> and C<system>.
! 
! =item Mac OS X
! 
! OS X has no support for namespaces.
! 
! =item Solaris
! 
! Solaris has no support for namespaces.
! 
! =back
! 
! =head2 Flags
! 
! The functions take a hash reference as their final parameter,
! which can specify flags to modify the behaviour of the functions.
! The flags specific to a function are documented in the function's
! description.
! 
! All functions support a C<namespace> flag. E.g.:
! 
!   use File::ExtAttr ':all';
!   use IO::File;
!   
!   # Manipulate the extended attributes of files.
!   setfattr('foo.txt', 'colour', 'red') || die;
!   my $colour = getfattr('bar.txt', 'colour', { namespace => 'user');
! 
! If no namespace is specified, the default namespace will be used.
! On Linux and *BSD the default namespace will be C<user>.

  =cut
***************
*** 136,140 ****
  }

! =item getfattr([$filename | $filehandle], $attrname, [$flags])

  Return the value of the attribute named C<$attrname>
--- 191,195 ----
  }

! =item getfattr([$filename | $filehandle], $attrname, [\%flags])

  Return the value of the attribute named C<$attrname>
***************
*** 142,147 ****
  C<$filehandle> (which should be an IO::Handle).

- C<$flags> are currently unused.
- 
  If no attribute is found, returns C<undef>. Otherwise gives a warning.

--- 197,200 ----
***************
*** 159,163 ****
  }

! =item setfattr([$filename | $filehandle], $attrname, $attrval, [$flags])

  Set the attribute named C<$attrname> with the value C<$attrval>
--- 212,216 ----
  }

! =item setfattr([$filename | $filehandle], $attrname, $attrval, [\%flags])

  Set the attribute named C<$attrname> with the value C<$attrval>
***************
*** 165,168 ****
--- 218,223 ----
  C<$filehandle> (which should be an IO::Handle).

+ XXX: FIXME: Below
+ 
  C<$flags> allows control of whether the attribute should be created
  or should replace an existing attribute's value. The value
***************
*** 191,195 ****
  }

! =item delfattr([$filename | $filehandle], $attrname, [$flags])

  Delete the attribute named C<$attrname> for the file named C<$filename>
--- 246,250 ----
  }

! =item delfattr([$filename | $filehandle], $attrname, [\%flags])

  Delete the attribute named C<$attrname> for the file named C<$filename>
***************
*** 197,202 ****
  (which should be an IO::Handle).

- C<$flags> are currently unused.
- 
  Returns true on success, otherwise false and a warning is issued.

--- 252,255 ----
***************
*** 214,224 ****
  }

! =item listfattr([$filename | $filehandle], [$flags])

  Return the attributes on the file named C<$filename> or referenced by the open
  filehandle C<$filehandle> (which should be an IO::Handle).

- C<$flags> are currently unused.
- 
  Returns undef on failure and $! will be set.

--- 267,275 ----
  }

! =item listfattr([$filename | $filehandle], [\%flags])

  Return the attributes on the file named C<$filename> or referenced by the open
  filehandle C<$filehandle> (which should be an IO::Handle).

  Returns undef on failure and $! will be set.

***************
*** 247,252 ****
  None by default.

! You can request that C<getfattr>, C<setfattr> and C<delfattr> be exported
! using the tag ":all".

  =head2 Exportable constants
--- 298,303 ----
  None by default.

! You can request that C<getfattr>, C<setfattr>, C<delfattr>
! and C<listfattr> be exported using the tag ":all".

  =head2 Exportable constants