The File System: 5.4 Files: File Utilities

FileDelete(), FileRename(), FileCopy(), FileMove(),FileGetDiskHandle()

Most of the time, such actions as copying, deleting, and renaming files are handled by desktop management programs like GeoManager. However, other geodes may need to perform these actions themselves. For example, if you use a temporary file, you may wish to delete it when you're done. The GEOS file system provides routines for these situations. One file utility, FileEnum() , is elaborate enough to be treated in its own section; for details, see FileEnum() .

To delete a file, call FileDelete() . This routine takes one argument, namely the address of a path string. If it can delete the file, it returns zero; otherwise, it returns an error code. Common error conditions include the following:

ERROR_FILE_NOT_FOUND: No such file exists in the specified directory.
ERROR_PATH_NOT_FOUND: An invalid path string was passed.
ERROR_ACCESS_DENIED: You do not have permission to delete that file, or it exists on a read-only volume.
ERROR_FILE_IN_USE: Some geode has that file open.

To change a file's name, call FileRename() . This routine takes two arguments: a pointer to the path string specifying the file, and a pointer to a string specifying the new name for the file. If successful, FileRename() returns zero; otherwise, it returns one of the above error codes.

To make a copy of a file, call FileCopy() . This routine takes four arguments: the handles of the source and destination disks (which may be the same), and the addresses of source and destination path strings. Passing a disk handle of zero indicates the current path's disk. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory. FileCopy() will make a copy of the file in the specified location with the specified name. If a file with that name and location already exists, it will be overwritten. FileCopy() returns zero if successful. Otherwise it returns one of the following error codes:

ERROR_FILE_NOT_FOUND: No such source file exists in the specified directory.
ERROR_PATH_NOT_FOUND: An invalid source or destination path string was passed.
ERROR_ACCESS_DENIED: You do not have permission to delete the existing copy of the destination file, or the destination disk or directory is not writable.
ERROR_FILE_IN_USE: Some geode has the existing destination file open.
ERROR_SHORT_READ_WRITE: There was not enough room on the destination disk. The destination disk will be left unchanged (i.e. a partial copy of the file will not be made).

To move a file from one directory to another, either on the same disk or on different disks, call FileMove() . This routine takes four arguments: the handles of the source and destination disks (which may be the same), and pointers to source and destination path strings. Passing a null disk handle indicates the current working directory. Each string specifies a path relative to the location specified by the corresponding disk handle. If the handle is a disk handle, the path is relative to that disk's root. If the disk handle is a standard path constant, the path string is relative to that standard path. If the disk handle is null, the path is relative to the current working directory. If the copy is successful, FileMove() will return zero; otherwise, it will return one of the above error codes.

If you want to find out the handle of the disk containing an open file, call FileGetDiskHandle() . This routine is passed the file handle; it returns the disk handle. This is useful if the geode has to prepare for a shutdown; it can get the disk handle with FileGetDiskHandle() , then save that handle with DiskSave() (see Saving and Restoring a Disk Handle ). With this information (and the file name), the geode will be able to reopen the file when it restarts.

GEOS SDK TechDocs |

5.3 GEOS Extended Attributes | Next:

5.5 FileEnum()