Inside Macintosh: Files /

Chapter 1 - Introduction to File Management

Summary of File Management

Pascal Summary

Constants

CONST
   {Gestalt constants}
   gestaltFSAttr           =  'fs  ';  {file system attributes selector}
   gestaltHasFSSpecCalls   =  1;       {supports FSSpec records}
   gestaltStandardFileAttr =  'stdf';  {Standard File attributes selector}
   gestaltStandardFile58   =  0;       {supports StandardPutFile etc.}
   gestaltFindFolderAttr   =  'fold';  {FindFolder attributes selector}
   gestaltFindFolderPresent=  0;       {FindFolder is present}
   {access modes for opening files}
   fsCurPerm         =  0;       {whatever permission is allowed}
   fsRdPerm          =  1;       {read permission}
   fsWrPerm          =  2;       {write permission}
   fsRdWrPerm        =  3;       {exclusive read/write permission}
   fsRdWrShPerm      =  4;       {shared read/write permission}
   {file mark positioning modes}
   fsAtMark          =  0;       {at current mark}
   fsFromStart       =  1;       {set mark relative to beginning of file}
   fsFromLEOF        =  2;       {set mark relative to logical end-of-file}
   fsFromMark        =  3;       {set mark relative to current mark}
   rdVerify          =  64;      {add to above for read-verify}
   {messages from CountAppFiles}
   appOpen           =  0;       {open the document(s)}
   appPrint          =  1;       {print the document(s)}

Data Types

File System Specification Record

TYPE FSSpec          =
   RECORD
      vRefNum:       Integer;    {volume reference number}
      parID:         LongInt;    {directory ID of parent directory}
      name:          Str63;      {filename or directory name}
   END;

   FSSpecPtr         =  ^FSSpec;
   FSSpecHandle      =  ^FSSpecPtr;

Standard File Reply Record

TYPE StandardFileReply=
   RECORD
      sfGood:        Boolean;    {TRUE if user did not cancel}
      sfReplacing:   Boolean;    {TRUE if replacing file with same name}
      sfType:        OSType;     {file type}
      sfFile:        FSSpec;     {selected item}
      sfScript:      ScriptCode; {script of selected item's name}
      sfFlags:       Integer;    {Finder flags of selected item}
      sfIsFolder:    Boolean;    {selected item is a folder}
      sfIsVolume:    Boolean;    {selected item is a volume}
      sfReserved1:   LongInt;    {reserved}
      sfReserved2:   Integer;    {reserved}
   END;

Application Files Record

TYPE AppFile         =
   RECORD
      vRefNum:       Integer;    {working directory reference number}
      fType:         OSType;     {file type}
      versNum:       Integer;    {version number; ignored}
      fName:         Str255;     {filename}
   END;
   SFTypeList        =  ARRAY[0..3] OF OSType;
   FileFilterProcPtr =  ProcPtr; {file filter function}

File Specification Routines

Opening Files

PROCEDURE StandardGetFile	(fileFilter: FileFilterProcPtr;
				numTypes: Integer; typeList: SFTypeList; 
				VAR reply: StandardFileReply);

Saving Files

PROCEDURE StandardPutFile	(prompt: Str255; defaultName: Str255; 
				VAR reply: StandardFileReply);

File Access Routines

Reading, Writing, and Closing Files

FUNCTION FSRead			(refNum: Integer; VAR count: LongInt; 
				buffPtr: Ptr): OSErr;
FUNCTION FSWrite		(refNum: Integer; VAR count: LongInt; 
				buffPtr: Ptr): OSErr;
FUNCTION FSClose		(refNum: Integer): OSErr;

Manipulating the File Mark

FUNCTION GetFPos		(refNum: Integer; VAR filePos: LongInt): OSErr;
FUNCTION SetFPos		(refNum: Integer; posMode: Integer; 
				posOff: LongInt): OSErr;

Manipulating the End-of-File

FUNCTION GetEOF			(refNum: Integer; VAR logEOF: LongInt): OSErr;
FUNCTION SetEOF			(refNum: Integer; logEOF: LongInt): OSErr;

File and Directory Manipulation Routines

Opening, Creating, and Deleting Files

FUNCTION FSpOpenDF		(spec: FSSpec; permission: SignedByte; 
				VAR refNum: Integer): OSErr;
FUNCTION FSpCreate		(spec: FSSpec; creator: OSType; 
				fileType: OSType; scriptTag: ScriptCode): 
				OSErr;
FUNCTION FSpDelete		(spec: FSSpec): OSErr;

Exchanging the Data in Two Files

FUNCTION FSpExchangeFiles	(source: FSSpec; dest: FSSpec): OSErr;

Creating File System Specifications

FUNCTION FSMakeFSSpec		(vRefNum: Integer; dirID: LongInt;
				fileName: Str255; VAR spec: FSSpec): OSErr;

Volume Access Routines

Updating Volumes

FUNCTION FlushVol		(volName: StringPtr; vRefNum: Integer): OSErr;

Obtaining Volume Information

FUNCTION GetVInfo		(drvNum: Integer; volName: StringPtr; 
				VAR vRefNum: Integer; VAR freeBytes: LongInt): 
				OSErr;
FUNCTION GetVRefNum		(refNum: Integer; VAR vRefNum: Integer): OSErr;

Application Launch File Routines

PROCEDURE GetAppParms		(VAR apName: Str255; VAR apRefNum: Integer; 
				VAR apParam: Handle);
PROCEDURE CountAppFiles		(VAR message: Integer; VAR count: Integer);
PROCEDURE GetAppFiles		(index: Integer; VAR theFile: AppFile);
PROCEDURE ClrAppFiles		(index: Integer);

C Summary

Constants

/*Gestalt constants*/
#define gestaltFSAttr            'fs  '   /*file system attributes selector*/
#define gestaltFullExtFSDispatching 0     /*exports HFSDispatch traps*/
#define gestaltHasFSSpecCalls       1     /*supports FSSpec records*/
#define gestaltFindFolderAttr    'fold'   /*FindFolder attributes selector*/
#define gestaltFindFolderPresent    0     /*FindFolder is present*/
/*Gestalt Standard File attributes selector and reply*/
#define gestaltStandardFileAttr  'stdf'
#define gestaltStandardFile58       0
/*values for requesting file read/write permissions*/
enum {
   fsCurPerm            = 0,     /*whatever permission is allowed*/
   fsRdPerm             = 1,     /*read permission*/
   fsWrPerm             = 2,     /*write permission*/
   fsRdWrPerm           = 3,     /*exclusive read/write permission*/
   fsRdWrShPerm         = 4};    /*shared read/write permission*/
/*file mark positioning modes*/
enum {
   fsAtMark             = 0,     /*at current mark}
   fsFromStart          = 1,     /*set mark relative to beginning of file*/
   fsFromLEOF           = 2,     /*set mark relative to logical end-of-file*/
   fsFromMark           = 3,     /*set mark relative to current mark*/
   rdVerify             = 64};   /*add to above for read-verify*/
/*messages from CountAppFiles*/
enum {
   appOpen              =  0,    /*open the document(s)*/
   appPrint             =  1};   /*print the document(s)*/

Data Types

File System Specification Record

struct FSSpec  {                    /*file system specification*/
      short       vRefNum;          /*volume reference number*/
      long        parID;            /*directory ID of parent directory*/
      Str63       name;             /*filename or directory name*/
};

typedef struct FSSpec FSSpec;
typedef FSSpec *FSSpecPtr;
typedef FSSpecPtr *FSSpecHandle;

Standard File Reply Record

struct StandardFileReply {       /*enhanced standard file reply record*/
      Boolean        sfGood;     /*TRUE if user did not cancel*/
      Boolean        sfReplacing;/*TRUE if replacing file with same name*/
      OSType         sfType;     /*file type*/
      FSSpec         sfFile;     /*selected file, folder, or volume*/
      ScriptCode     sfScript;   /*script of file, folder, or volume name*/
      short          sfFlags;    /*Finder flags of selected item*/
      Boolean        sfIsFolder; /*selected item is a folder*/
      Boolean        sfIsVolume; /*selected item is a volume*/
      long           sfReserved1;/*reserved*/
      short          sfReserved2;/*reserved*/
};

typedef struct StandardFileReply StandardFileReply;

Application Files Record

struct AppFile {
      short          vRefNum;    /*working directory reference number*/
      OSType         fType;      /*file type*/
      short          versNum;    /*version number; ignored*/
      Str255         fName;      /*filename*/
   END;

typedef struct AppFile AppFile;

Standard File Type List

typedef OSType SFTypeList[4];

Callback Routine Pointer Types

/*file filter function*/
typedef pascal Boolean (*FileFilterProcPtr)
   (ParmBlkPtr PB);

File Specification Routines

Opening Files

pascal void StandardGetFile	(const Str255 prompt,
				FileFilterProcPtr fileFilter, 
				short numTypes, SFTypeList typeList, 
				StandardFileReply *reply);

Saving Files

pascal void StandardPutFile	(const Str255 prompt, const Str255 defaultName, 
				StandardFileReply *reply);

File Access Routines

Reading, Writing, and Closing Files

pascal OSErr FSRead		(short refNum, long *count, Ptr buffPtr);
pascal OSErr FSWrite		(short refNum, long *count, Ptr buffPtr);
pascal OSErr FSClose		(short refNum);

Manipulating the File Mark

pascal OSErr GetFPos		(short refNum, long *filePos);
pascal OSErr SetFPos		(short refNum, short posMode, long posOff);

Manipulating the End-of-File

pascal OSErr GetEOF		(short refNum, long *logEOF);
pascal OSErr SetEOF		(short refNum, long logEOF);

File and Directory Manipulation Routines

Opening, Creating, and Deleting Files

pascal OSErr FSpOpenDF		(const FSSpec *spec, char permission, 
				short *refNum);
pascal OSErr FSpCreate		(const FSSpec *spec, OSType creator, 
				OSType fileType, ScriptCode scriptTag);
pascal OSErr FSpDelete		(const FSSpec *spec);

Exchanging the Data in Two Files

pascal OSErr FSpExchangeFiles
   				(const FSSpec *source, const FSSpec *dest);

Creating File System Specifications

pascal OSErr FSMakeFSSpec	(short vRefNum, long dirID, 
				ConstStr255Param fileName, FSSpecPtr spec);

Volume Access Routines

Updating Volumes

pascal OSErr FlushVol 		(StringPtr volName, short vRefNum);

Obtaining Volume Information

pascal OSErr GetVInfo		(short drvNum, StringPtr volName,
				short *vRefNum, long *freeBytes);
pascal OSErr GetVRefNum		(short refNum, short *vRefNum);

Application Launch File Routines

pascal void GetAppParms		(Str255 apName, short *apRefNum, 
				Handle *apParam);
pascal void CountAppFiles	(short *message, short *count);
pascal void GetAppFiles		(short index, AppFile *theFile);
pascal void ClrAppFiles		(short index);

Assembly-Language Summary

Global Variables

AppParmHandle	long	Handle to Finder information.
CurApName	32 bytes	Name of current application (length byte followed by up to 31 characters).
CurApRefNum	word	Reference number of current application's resource file.

Result Codes

noErr	0	No error
dirFulErr	-33	File directory full
dskFulErr	-34	All allocation blocks on the volume are full
nsvErr	-35	Volume not found
ioErr	-36	I/O error
bdNamErr	-37	Bad filename or volume name
fnOpnErr	-38	File not open
eofErr	-39	Logical end-of-file reached
posErr	-40	Attempt to position mark before start of file
tmfoErr	-42	Too many files open
fnfErr	-43	File not found
wPrErr	-44	Hardware volume lock
fLckdErr	-45	File locked
vLckdErr	-46	Software volume lock
fBsyErr	-47	File is busy; one or more files are open; directory not empty or working directory control block is open
dupFNErr	-48	A file with the specified name and version number already exists
opWrErr	-49	File already open for writing
paramErr	-50	Parameter error
rfNumErr	-51	Reference number specifies nonexistent access path
gfpErr	-52	Error during GetFPos
volOfflinErr	-53	Volume is offline
permErr	-54	Attempt to open locked file for writing
nsDrvErr	-56	Specified drive number doesn't match any number in the drive queue
wrPermErr	-61	Read/write permission doesn't allow writing
dirNFErr	-120	Directory not found or incomplete pathname
wrgVolTypErr	-123	Not an HFS volume
notAFileErr	-1302	Specified file is a directory
diffVolErr	-1303	Files are on different volumes
sameFileErr	-1306	Source and destination files are the same
afpAccessDenied	-5000	User does not have the correct access to the file
afpObjectTypeErr	-5025	Object is a directory, not a file; a directory exists with that name
afpSameObjectErr	-5038	Source and destination files are the same