/ 
MacOSX-File-0.68
River stage zero No dependents
/ MacOSX::File::Catalog

NAME

MacOSX::File::Catalog - Get (HFS) Catalog Information for that file

SYNOPSIS

use MacOSX::File::Catalog;
$catalog = MacOSX::File::Catalog->get($path);
$catalog->type('TEXT');
$catalog->creator('ttxt');
$catalog->flags(-invisible => 1);
$catalog->set;

DESCRIPTION

This module allows you to get all gettable attributes of the file or directory specified and set all settable attributes thereof. This module is a superset of MacOSX::File::Info. You can also think this module as stat() for HFS.

EXPORT

Subs: getcatalog(), setcatalog()

METHODS

$catalog = MacOSX::File::Catalog->get($path);
$catalog = getfileinfo($path);

Constructs MacOSX::File::Catalog from which you can manipulate file attributes. On failure, it returns undef and $MacOSX::File::OSErr is set.

$catalog->set([$path]);
setcatalog($catalog, [$path]);

Sets file attributes of file $path. If $path is omitted the file you used to construct $catalog is used. On success, it returns 1. On failure, it returns 0 and $MacOSX::File::OSErr is set.

Remember any changes to $catalog will not be commited until you call these functions.

ex)
  setcatalog(getcatalog("foo"), "bar"); 
  #Copies file attributes from foo to bar
$catalog->dump

returns a pretty-printed string that contains the value of every (gettable) member of FSCatalogInfo structure.

ex) print $catalog->dump;

file lock

The file lock status is stored in $catalog->nodeFlags but this field is supposed to be read-only. Use the following methods instead

$catalog->locked
$catalog->lock
$catalog->unlock

Read-only access methods

The following methods returns the value of each field;

$catalog->ref              Used Internally to store FSRef
$catalog->nodeFlags        see lock() method
$catalog->volume           vRefnum there of. Corresponds to st_dev
$catalog->parentDirID      dirID thereof 
                           equiv. to lstat(dirname($path))->ino;
$catalog->nodeID           nodeID thereof
                           equiv. to lstat($path)->ino;
$catalog->sharingFlags    
$catalog->userPrivileges
$catalog->valence

Access methods with scalar argument

The following methods returns the value of each field without argument. With argument, it sets the value within.

$catalog->createDate

Content Creation Date. equiv. to stat($path)->ctime

$catalog->contentModDate

Content Modification Date. equiv. to stat($path)->mtime

$catalog->attributeModDate

Attribute Modification Date. Unlike Unix, this value is stored as file attribute. On Unix, mtime of the containing directory would be changed.

$catalog->accessDate

Content Access date. equiv. to stat($path)->atime

$catalog->backupDate

Backup date. This field is hardly ever used.

$catalog->textEncodingHint

Text Encoding Hint

Note that dates in this module is stored as double while catalog stores as UTCDateTime, which is a 64bit fixed floating point. 48bits are for integral part and 16bits are for fractional part. The conversion is done automagically but it won't hurt you to know.

Access methods with list argument

The following methods returns the value of each field as list context without argument. With argument, it sets the value within. when fewer arguments are fed, only first arguments are set with the remaining fields untouched.

eg) $catalog->finderInfo('TEXT', 'ttxt') # changes type and creator with flags and others unchanged

($uid, $gid, $mode, $specialDevice) = $catalog->permissions(...)

returns 4-element list whose values are UID, GID, MODE there of.

SEE http://developer.apple.com/technotes/tn/tn1150.html#HFSPlusPermissions for the use of this field.

($type, $creator, $flags, $location, $fdfldr) = $catalog->finderInfo(...)

returns 5-element list whose values are type, creator, flags, location and folder information. Only first 3 would be relevant for you. Note this module contains no ->flags method, unlike MacOSX::File::Info module.

($iconID, $script, $xflags, $comment, $putaway) = $catalog->extFinderInfo(...)

returns 5-element list whose values are iconID, xflags, comment and putaway values. I confess I know nothing about this field; I just faithfully coded accordingly to Carbon document. Leave it as it is unless you know what you are doing.

AUTHOR

Dan Kogai <dankogai@dan.co.jp>

SEE ALSO

MacPerl

Inside Carbon: File Manager http://developer.apple.com/techpubs/macosx/Carbon/Files/FileManager/File_Manager/index.html

COPYRIGHT

Copyright 2002 Dan Kogai <dankogai@dan.co.jp>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.