FileOpen()

FileHandle FileOpen( /* sets thread's error value */
        const char		* name,			/* relative to working dir */
        FileAccessFlags		flags);			/* Permissions/exclusions */

This routine opens a file for bytewise access. The file may be a DOS file or a GEOS byte file. If the file is successfully opened, FileOpen() will return the file's handle; otherwise, it will return a null handle and set the thread's error value (accessible via ThreadGetError() ). Errors typically set by this routine are listed below:

ERROR_FILE_NOT_FOUND: No file with the specified name could be found in the appropriate directory.
ERROR_PATH_NOT_FOUND: A relative or absolute path had been 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, FileOpen() 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.

See Also: FileCreate(), FileAccessFlags.

Include: file.h

FileParseStandardPath()

StandardPath FileParseStandardPath(
        DiskHandle		disk,
        const char		** path);

This routine is passed a full path (relative to the passed disk or a standard path, if the disk handle is null) and finds the standard path which most closely contains that path. It updates the pointer whose address is passed so that it points to the trailing portion of the path string. For example, if you pass the path string "\GEOWORKS\DOCUMENT\MEMOS\APRIL", the pointer would be updated to point to the "\MEMOS\APRIL" portion, and the StandardPath SP_DOCUMENT would be returned. If the path passed does not belong to a standard path, the constant SP_NOT_STANDARD_PATH will be returned, and the pointer will not be changed.

Include: file.h

FilePopDir()

void	FilePopDir();

FilePopDir() pops the top directory off the thread's directory stack and makes it the current working directory.

See Also: FilePushDir().

Include: file.h

FilePos()

dword	FilePos( /* Sets thread's error value */
        FileHandle		fh,
        dword		posOrOffset,
        FilePosMode		mode);

This routine changes the current file position. The position can be specified in three ways, depending on the value of the mode argument:

FILE_POS_START: The file position is set to a specified number of bytes after the start of the file. Passing this mode with an offset of zero will set the file position to the start of the file.
FILE_POS_RELATIVE: The file position is incremented by a specified number of bytes; this number may be negative.
FILE_POS_END: The file position is set to a specified number of bytes after the end of the file; it is usually passed with a negative number of bytes. Passing this mode with an offset of zero will set the file position to the end of the file.

FilePos() returns a 32-bit integer. This integer specifies the absolute file position after the move (relative to the start of the file). On an error, it sets the thread's error value (accessible via ThreadGetError() ).

Tips and Tricks: To find out the current file position without changing it, call FilePos() with mode FILE_POS_RELATIVE and offset zero.

Include: file.h

FilePushDir()

void	FilePushDir();

FilePushDir() pushes the current working directory onto the thread's directory stack. It does not change the current working directory.

See Also: FilePopDir().

Include: file.h

FileRead()

word	FileRead(
        FileHandle		fh,			/* handle of open file */
        void		* buf,			/* copy data to this buffer */
        word		count,			/* Length of buffer (in bytes) */
        Boolean		noErrorFlag);					/* Set if app can't
							 * handle errors */

This routine copies data from a file into memory. It starts copying from the current position in the file. If possible, it will copy enough data to fill the buffer. If FileRead() is successful, it returns the number of bytes copied. If an error occurs, FileRead() returns -1 and sets the thread's error value (usually to ERROR_ACCESS_DENIED). The current file position will be changed to the first byte after the ones which were read.

In C, there is no way to determine whether an ERROR_SHORT_READ_WRITE error occurs. To check whether all of the data was actually copied into memory, you must compare the number of bytes actually read with the number requested to be read. If your read operation requires multiple FileRead() operations, you may should read until zero bytes are returned.

To retrieve the thread error value, use ThreadGetError() .

If the argument noErrorFlag is set to true (i.e. non-zero), FileRead() will fatal-error if an error occurs (including an ERROR_SHORT_READ_WRITE).

Warnings: Pass noErrorFlag true only during debugging.

Include: file.h