FileCreate()

FileHandle 	FileCreate( /* sets thread's error value */
        const char		* name,				/* relative to working directory */
        FileCreateFlags		flags,				/* see below */
        FileAttrs		attributes);				/* FileAttrs of new file */

This routine creates a byte file. The file may be a DOS file or a GEOS byte file. If the file is successfully opened, FileCreate() will return the file's handle; otherwise, it will return a null handle and set the thread's error value.

The second parameter is a word-length FileCreateFlags record. The third parameter, attributes , describes the FileAttrs record to be set for the new file.

If successful, FileCreate() returns the file's handle. If it is unsuccessful, it returns a null handle and sets the thread's error value (accessible via ThreadGetError() ). The following error values are commonly returned:

ERROR_PATH_NOT_FOUND: A relative or absolute path was passed, and the path included a directory which did not exist.
ERROR_TOO_MANY_OPEN_FILES: There is a limit to how many files may be open at once. If this limit is reached, FileCreate() will fail until a file is closed.
ERROR_ACCESS_DENIED: Either the caller requested access which could not be granted (e.g. it requested write access when another geode had already opened the file with FILE_DENY_W), or the caller tried to deny access when that access had already been granted to another geode (e.g. it tried to open the file with FILE_DENY_W when another geode already had it open for write-access).
ERROR_WRITE_PROTECTED: The caller requested write or read-write access to a file in a write-protected volume.
ERROR_FILE_EXISTS: Returned if FileCreate() was called with FILE_CREATE_ONLY and a file with the specified name already exists.
ERROR_FILE_FORMAT_MISMATCH: Returned if FileCreate() was called with FILE_CREATE_TRUNCATE or FILE_CREATE_NO_TRUNCATE and a file exists in a different format than desired; i.e. you passed FCF_NATIVE and the file already exists in the GEOS format, or vice versa.

Examples: An example of usage is shown below.

Example of FileCreate() usage

/* Here we create a DOS file in the current working directory. If the file already
 * exists, we open the existing file and truncate it.
 */

	FileHandle		newFile;

	newFile = 		FileCreate("NEWFILE.TXT",
					( (FILE_CREATE_TRUNCATE | FCF_NATIVE)
					 | (FILE_ACCESS_RW | FILE_DENY_RW)),
					0); /* set no attribute bits */

See Also: FileCreateTempFile(), FileOpen().

Include: file.h

FileCreateDir()

word	FileCreateDir( /* Returns error & sets thread's error value */
        const char * name);				/* Relative path of new directory */

This routine creates a new directory. The parameter is a path string; the path is relative to the current directory. The last element of the path string must be the directory to create.

If FileCreateDir() is successful, it returns zero and clears the thread's error value. Otherwise, it returns an error code and sets the thread's error value (accessible via ThreadGetError() ). The following errors are returned:

ERROR_PATH_TOO_LONG: The path string was longer than is permitted by the file system for that device.
ERROR_FILE_EXISTS: A file or directory with the specified name already exists at the specified location.
ERROR_INVALID_NAME: The name passed was inappropriate for directories on that device.
ERROR_DISK_STALE: The drive that disk was on has been removed.
ERROR_DISK_UNAVAILABLE: The validation of the disk in that drive was aborted by the user.
ERROR_PATH_NOT_FOUND: The path string was in some way invalid; for example, it might have instructed FileCreateDir() to create the directory within a directory which does not exist.
ERROR_ACCESS_DENIED: The thread is not able to create directories in the specified location, or a directory with the specified name already exists.
ERROR_WRITE_PROTECTED: The volume is write-protected.

See Also: FileDeleteDir().

Include: file.h

FileCreateTempFile()

FileHandle FileCreateTempFile( /* Sets thread's error value */
        char		* dir,		/* directory, relative to working dir.;
					 * file name replaces 14 trailing null
					 * characters upon return */

        FileCreateFlags		flags,
        FileAttrs		attributes);

This routine creates and opens a temporary file in the directory specified. The routine automatically selects a name for the temporary file. No creation flags are needed, since the file will definitely be created anew and will be used only by this geode. The directory string must end with fourteen null bytes (enough to be replaced by the new file's name).

If FileCreateTempFile() is successful, it returns the file's handle as well as the string passed in dir , with the trailing null characters replaced by the file name. If it is unsuccessful, it returns a null handle and sets the thread's error value to a member of the FileError enumerated type. (This error value is accessible via ThreadGetError() .)

Tips and Tricks: Temporary files are usually created in a subdirectory of SP_PRIVATE_DATA.

See Also: FileCreate().

Include: file.h

FileDelete()

word	FileDelete( /* returns error */
        const char * name);			/* path relative to working directory */

This routine deletes a file. If it is successful, it returns zero; otherwise, it returns a FileError . Common errors include:

ERROR_FILE_NOT_FOUND: No such file exists in the specified directory.
ERROR_WRITE_PROTECTED: The volume is write-protected.
ERROR_PATH_NOT_FOUND: An invalid path string was passed.
ERROR_ACCESS_DENIED: You do not have permission to delete that file.
ERROR_FILE_IN_USE: Some geode has that file open.

Include: file.h