This chapter provides reference material for the File Stream API. It is organized as follows:
File Stream Structures and Types
File Stream Constants
File Stream Functions and Macros
The header file FileStream.h
declares the API that this chapter describes.
For more information on file streams in Palm OS®, see Chapter 2, "Palm OS Databases."
File Stream Structures and Types
FileHand Typedef
Purpose
Handle to an open file stream.
Declared In
FileStream.h
Prototype
typedef MemHandle FileHand
Comments
Open a file stream and receive a handle to it with FileOpen()
.
File Stream Constants
File Stream Error Codes
Purpose
Error codes returned by the various File Stream functions.
Declared In
FileStream.h
Constants
-
#define fileErrCloseError (fileErrorClass | 12)
- Error closing the stream.
-
#define fileErrCorruptFile (fileErrorClass | 3)
- The stream is corrupted, invalid, or not a stream.
-
#define fileErrCreateError (fileErrorClass | 7)
- Couldn't create new stream.
-
#define fileErrEOF (fileErrorClass | 16)
- End-of-File error.
-
#define fileErrInUse (fileErrorClass | 9)
- Stream couldn't be opened or deleted because it is in use.
-
#define fileErrInvalidDescriptor (fileErrorClass | 11)
- Invalid file descriptor
(FileHandle).
-
#define fileErrInvalidParam (fileErrorClass | 2)
- Invalid parameter value passed.
-
#define fileErrIOError (fileErrorClass | 15)
- Generic I/O error.
-
#define fileErrMemError (fileErrorClass | 1)
- Out of memory error.
-
#define fileErrNotFound (fileErrorClass | 4)
- Couldn't find the stream.
-
#define fileErrNotStream (fileErrorClass | 17)
- Attempted to open an entity that is not a stream.
-
#define fileErrOpenError (fileErrorClass | 8)
- Generic open error.
-
#define fileErrOutOfBounds (fileErrorClass | 13)
- Attempted operation went out of bounds of the stream.
-
#define fileErrPermissionDenied (fileErrorClass | 14)
- Couldn't write to a stream open for read-only access.
-
#define fileErrReadOnly (fileErrorClass | 10)
- Couldn't open in write mode because existing stream is read-only.
-
#define fileErrReplaceError (fileErrorClass | 6)
- Couldn't replace existing stream.
-
#define fileErrTypeCreatorMismatch (fileErrorClass | 5)
- Type and/or creator not what was specified.
Primary Open Modes
Purpose
Specify the mode in which a file stream is opened.
Declared In
FileStream.h
Constants
-
#define fileModeAllFlags ( fileModeReadOnly | fileModeReadWrite | fileModeUpdate | fileModeAppend | fileModeLeaveOpen | fileModeExclusive | fileModeAnyTypeCreator | fileModeTemporary | fileModeDontOverwrite )
- The complete set of file stream open modes.
-
#define fileModeAppend (0x10000000UL)
- Open/create for read/write, always writing to the end of the stream
-
#define fileModeReadOnly (0x80000000UL)
- Open for read-only access
-
#define fileModeReadWrite (0x40000000UL)
- Open/create for read/write access, discarding any previous version of stream
-
#define fileModeUpdate (0x20000000UL)
- Open/create for read/write, preserving previous version of stream if it exists
Comments
For each file stream, you must pass to the FileOpen()
function only one of the primary mode selectors listed. Note that you can combine the primary mode selector with one or more secondary mode selectors for additional control.
Secondary Open Modes
Purpose
Additional mode selectors that can be OR'd with a primary mode selector to provide additional control.
Declared In
FileStream.h
Constants
-
#define fileModeAnyTypeCreator (0x02000000UL)
- Accept any type/creator when opening or replacing an existing stream. Normally, the
FileOpen()
function opens only streams having the specified creator and type. Setting this option enables theFileOpen()
function to open streams having a type or creator other than those specified. -
#define fileModeDontOverwrite (0x00800000UL)
- Prevents
fileModeReadWrite
from discarding an existing stream having the same name; may only be specified together withfileModeReadWrite
. -
#define fileModeExclusive (0x04000000UL)
- No other application can open the stream until the application that opened it in this mode closes it.
-
#define fileModeLeaveOpen (0x08000000UL)
- Leave stream open when application quits. Palm OS Cobalt applications should not use this option.
-
#define fileModeTemporary (0x01000000UL)
- Delete the stream automatically when it is closed. For more information, see Comment section of
FileOpen()
function description.
Miscellaneous File Stream Constants
Purpose
The File Stream APIs also include the following #defines
.
Declared In
FileStream.h
Constants
FileOpEnum Enum
Purpose
Control operations that can be performed on a file stream with FileControl()
.
Declared In
FileStream.h
Constants
-
fileOpNone = 0
- No-op.
-
fileOpDestructiveReadMode
- Enter destructive read mode, and rewind stream to its beginning. Once in this mode, there is no turning back: stream's contents after closing (or crash) are undefined.
- Destructive read mode deletes blocks as data are read, thus freeing storage automatically. Once in destructive read mode, you cannot re-use the file stream—the contents of the stream are undefined after it is closed or after a crash.
- Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the
FileWrite()
,FileSeek()
, orFileTruncate()
functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, theFileWrite()
function can append data to the stream, but it also preserves the current stream position so that subsequent reads pick up where they left off (you can think of this as a pseudo-pipe). -
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- zero on success;
-
fileErr
... on error -
fileOpGetEOFStatus
- Get end-of-file status (like C runtime's
feof
) (err =fileErrEOF
). Indicates end of file condition. UseFileClearerr()
to clear this error status. -
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- zero if not end of file;
- non-zero if end of file
-
fileOpGetLastError
- Get error code from last operation on stream, and clear the last error code value. Doesn't change status of EOF or I/O errors —use
FileClearerr()
to reset all error codes. -
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- Error code from last file stream operation
-
fileOpClearError
- Clear I/O and EOF error status and last error.
-
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- zero on success;
fileErr
... on error -
fileOpGetIOErrorStatus
- Get I/O error status (like C runtime's
ferror
). UseFileClearerr()
to clear this error status. -
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- zero if not I/O error;
- non-zero if I/O error is pending.
-
fileOpGetCreatedStatus
- Find out whether file was created by
FileOpen()
function -
ARGUMENTS:
-
stream
= open stream handle -
valueP
= Pointer to Boolean -
valueLenP
= Pointer toInt32
variable set to sizeof(Boolean) -
RETURNS:
- zero on success;
fileErr
... on error. The Boolean variable will be set to non-zero if the file was created. -
fileOpGetOpenDbRef
- Get the open database reference (handle) of the underlying database that implements the stream (
NULL
if none); this is needed for performing Palm OS-specific operations on the underlying database, such as changing or getting creator and type, version, backup/reset bits, and so on.
WARNING! Do not make any changes to the data of the underlying database—doing so will corrupt the file stream.
-
fileOpFlush
- Flush any cached data to storage.
-
ARGUMENTS:
-
stream
= open stream handle -
valueP
=NULL
-
valueLenP
=NULL
-
RETURNS:
- zero on success;
fileErr
... on error; -
fileOpLAST
- Not an actual operator, this value simply identifies the end of the list of file control operations.
FileOriginEnum Enum
Purpose
File positions to which an offset is added (or subtracted, if the offset is negative) to get a seek position within the file.
Declared In
FileStream.h
Constants
-
fileOriginBeginning = 1
- From the beginning (first data byte of file).
-
fileOriginCurrent
- From the current position.
-
fileOriginEnd
- From the end of file (one position beyond last data byte).
Comments
Supply one of these values to FileSeek()
.
File Stream Functions and Macros
FileClearerr Macro
Purpose
Clear I/O error status, end of file error status, and last error.
Declared In
FileStream.h
Prototype
#define FileClearerr (
__stream__
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
See Also
FileGetLastError()
, FileRewind()
FileClose Function
Purpose
Close the file stream and destroy its handle. If the stream was opened with fileModeTemporary
, it is deleted upon closing.
Declared In
FileStream.h
Prototype
status_t FileClose (
FileHand stream
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
FileControl Function
Purpose
Perform a specified operation on a file stream.
Declared In
FileStream.h
Prototype
status_t FileControl ( FileOpEnumop
, FileHandstream
, void*valueP
, int32_t*valueLenP
)
Parameters
-
→ op
- The operation to perform, and its associated formal parameters. See "FileOpEnum" for a list of possible values.
-
→ stream
- Open stream handle if required for file stream operation.
-
↔ valueP
- Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the
op
parameter. For details, see "FileOpEnum." -
↔ valueLenP
- Pointer to value or buffer, as required. This parameter is defined by the selector passed as the value of the
op
parameter. For details, see "FileOpEnum."
Returns
Returns either a value defined by the selector passed as the argument to the op
parameter, or an error code resulting from the requested operation.
Comments
Normally, you do not call the FileControl()
function yourself; it is called for you by most of the other file streaming functions and macros to perform common file streaming operations. You can call FileControl()
yourself to enable specialized read modes.
See Also
FileClearerr()
, FileEOF()
, FileError()
, FileFlush()
, FileGetLastError()
, FileRewind()
FileDelete Function
Purpose
Deletes the specified file stream from the specified card. Only a closed stream may be passed to this function.
Declared In
FileStream.h
Prototype
status_t FileDelete ( const char*nameP
, uint32_tcreator
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
See Also
FileDeleteV50 Function
Purpose
Deletes the specified file stream from the specified card. Only a closed stream may be passed to this function.
Declared In
FileStream.h
Prototype
status_t FileDeleteV50 ( uint16_tcardNo
, const char*nameP
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS; the cardNo
parameter is ignored.
See Also
FileDmRead Macro
Purpose
Reads data from a file stream into a chunk, record, or resource residing in a database.
Declared In
FileStream.h
Prototype
#define FileDmRead (stream
,startOfDmChunkP
,destOffset
,objSize
,numObj
,errP
)
Parameters
-
→ stream
- Handle to an open stream.
-
→ startOfDmChunkP
- Pointer to beginning of chunk, record or resource residing in a database.
-
→ destOffset
- Offset from
startOfDmChunkP
(base pointer) to the destination area (must be >= 0). -
→ objSize
- Size of each stream object to read.
-
→ numObj
- Number of stream objects to read.
-
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for more information.
Returns
The number of whole objects that were read. Note that the number of objects actually read may be less than the number requested.
Comments
When the number of objects actually read is less than the number requested, you may be able to determine the cause of this result by examining the return value of the errP
parameter or by calling the FileGetLastError()
function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non-NULL
pointer was passed as the value of the errP
parameter when FileDmRead
was used and an error was encountered, *
errP
holds a non-zero error code when the function returns. In addition, the FileError()
and FileEOF()
functions may be used to check for I/O errors.
See Also
FileRead()
, FileError()
, FileEOF()
FileEOF Macro
Purpose
Get end-of-file status (err = fileErrEOF
indicates end of file condition).
Declared In
FileStream.h
Prototype
#define FileEOF (
__stream__
)
Parameters
Returns
Returns 0 if not at the end of file, fileErrEOF
if at the end of file, or an error code otherwise. See the section "File Stream Error Codes" for more information.
Comments
This macro's behavior is similar to that of the feof
function provided by the C programming language runtime library.
Use FileClearerr()
to clear the I/O error status.
See Also
FileClearerr()
, FileGetLastError()
, FileRewind()
FileError Macro
Purpose
Declared In
FileStream.h
Prototype
#define FileError (
__stream__
)
Parameters
Returns
Returns errNone
if no error, and non-zero if an I/O error indicator has been set for this stream. See the section "File Stream Error Codes" for more information.
Comments
This macro's behavior is similar to that of the C programming language's ferror
runtime function.
Use FileClearerr()
to clear the I/O error status.
See Also
FileClearerr()
, FileGetLastError()
, FileRewind()
FileFlush Macro
Purpose
Declared In
FileStream.h
Prototype
#define FileFlush (
__stream__
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
Comments
It is not always necessary to call this macro explicitly—certain operations flush the contents of a stream automatically; for example, streams are flushed when they are closed. Because this macro's behavior is similar to that of the fflush()
function provided by the C programming language runtime library, you only need to call it explicitly under circumstances similar to those in which you would call fflush
explicitly.
FileGetLastError Macro
Purpose
Get error code from last operation on file stream, and clear the last error code value (will not change end of file or I/O error status -- use FileClearerr()
to reset all error codes)
Declared In
FileStream.h
Prototype
#define FileGetLastError (
__stream__
)
Parameters
Returns
Returns the error code returned by the last file stream operation. See the section "File Stream Error Codes" for more information.
See Also
FileClearerr()
, FileEOF()
, FileError()
FileOpen Function
Purpose
Open existing file stream or create an open file stream (an extended database) for I/O in the specified mode.
Declared In
FileStream.h
Prototype
FileHand FileOpen ( const char*nameP
, uint32_ttype
, uint32_tcreator
, uint32_topenMode
, status_t*errP
)
Parameters
-
→ nameP
- Pointer to the name of the extended database to open or create as a file stream. This value must be a valid name—no wildcards allowed, and composed only of 7-bit ASCII characters—and must not be
NULL
. -
→ type
- File type of stream to open or create. Pass
0
for wildcard, in which casesysFileTFileStream
is used if the stream needs to be created andfileModeTemporary
is not specified. Iftype
is0
andfileModeTemporary
is specified, thensysFileTTemp
is used for the file type of the stream this function creates. -
→ creator
- Creator of stream to open or create. Pass
0
for wildcard, in which case the current application's creator ID is used for the creator of the stream this function creates. -
→ openMode
- Mode in which to open the file stream. You must specify only one primary mode selector. Additionally, you can use the bitwise inclusive OR operator to append one or more secondary mode selectors to the primary mode selector. See "Primary Open Modes" and "Secondary Open Modes" for the list of possible values.
-
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
If successful, returns a handle to an open file stream; otherwise, returns 0
.
In some cases, FileOpen()
returns a non-zero value when it has failed to open a file; thus, it is always a good idea to check the errP
parameter value to determine if an error has occurred.
Comments
IMPORTANT: Previous versions of Palm OS didn't enforce the requirement that database names passed to
FileOpen()
be composed only of 7-bit ASCII characters. Palm OS Cobalt requires that this be so.
The fileModeReadOnly
, fileModeReadWrite
, fileModeUpdate
, and fileModeAppend
modes are mutually exclusive—pass only one of them to the FileOpen()
function!
When the fileModeTemporary
open mode is used and the file type passed to FileOpen()
is 0
, the FileOpen()
function uses sysFileTTemp
(defined in SystemMgr.rh)
for the file type, as recommended. In future versions of Palm OS, this configuration will enable the automatic cleanup of undeleted temporary files after a system crash. Automatic post-crash cleanup is not implemented in current versions of Palm OS.
To open a file stream even if it has a different type and creator than specified, pass the fileModeAnyTypeCreator
selector as a flag in the openMode
parameter to the FileOpen()
function.
The fileModeLeaveOpen
mode is an esoteric option that most applications should not use. It may be useful for a library that needs to open a stream from the current application's context and keep it open even after the current application quits. By default, Palm OS automatically closes all databases that were opened in a particular application's context when that application quits. The fileModeLeaveOpen
option overrides this default behavior.
FileOpenV50 Function
Purpose
Open existing file stream or create an open file stream (a classic database) for I/O in the mode specified by the openMode
parameter.
Declared In
FileStream.h
Prototype
FileHand FileOpenV50 ( uint16_tcardNo
, const char*nameP
, uint32_ttype
, uint32_tcreator
, uint32_topenMode
, status_t*errP
)
Parameters
-
→ cardNo
- Card on which the file stream to open resides.
-
→ nameP
- Pointer to the name of the classic database to open or create as a file stream. This value must be a valid name—no wildcards allowed, and composed only of 7-bit ASCII characters—and must not be
NULL
. -
→ type
- File type of stream to open or create. Pass
0
for wildcard, in which casesysFileTFileStream
is used if the stream needs to be created andfileModeTemporary
is not specified. Iftype
is0
andfileModeTemporary
is specified, thensysFileTTemp
is used for the file type of the stream this function creates. -
→ creator
- Creator of stream to open or create. Pass
0
for wildcard, in which case the current application's creator ID is used for the creator of the stream this function creates. -
→ openMode
- Mode in which to open the file stream. You must specify only one primary mode selector. Additionally, you can use the bitwise inclusive OR operator to append one or more secondary mode selectors to the primary mode selector. See "Primary Open Modes" and "Secondary Open Modes" for the list of possible values.
-
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
If successful, returns a handle to an open file stream; otherwise, returns 0
.
In some cases, on some platforms, FileOpen()
returns a non-zero value when it has failed to open a file; thus, it is always a good idea to check the errP
parameter value to determine if an error has occurred.
Comments
IMPORTANT: Previous versions of Palm OS didn't enforce the requirement that database names passed to
FileOpen()
be composed only of 7-bit ASCII characters. Palm OS Cobalt requires that this be so.
The fileModeReadOnly
, fileModeReadWrite
, fileModeUpdate
, and fileModeAppend
modes are mutually exclusive—pass only one of them to the FileOpen()
function!
When the fileModeTemporary
open mode is used and the file type passed to FileOpen()
is 0
, the FileOpen()
function uses sysFileTTemp
(defined in SystemMgr.rh)
for the file type, as recommended. In future versions of Palm OS, this configuration will enable the automatic cleanup of undeleted temporary files after a system crash. Automatic post-crash cleanup is not implemented in current versions of Palm OS.
To open a file stream even if it has a different type and creator than specified, pass the fileModeAnyTypeCreator
selector as a flag in the openMode
parameter to the FileOpen()
function.
The fileModeLeaveOpen
mode is an esoteric option that most applications should not use. It may be useful for a library that needs to open a stream from the current application's context and keep it open even after the current application quits. By default, Palm OS automatically closes all databases that were opened in a particular application's context when that application quits. The fileModeLeaveOpen
option overrides this default behavior.
Compatibility
This function is only provided for compatibility with previous versions of Palm OS; the cardNo
parameter is ignored.
FileRead Macro
Purpose
Reads data from a stream into a buffer.
Declared In
FileStream.h
Prototype
#define FileRead (stream
,bufP
,objSize
,numObj
,errP
)
Parameters
-
→ stream
- Handle to an open stream.
-
→ bufP
- Pointer to a buffer into which data is read
-
→ objSize
- Size of each stream object to read.
-
→ numObj
- Number of stream objects to read.
-
← errP
- Pointer to a variable that is to hold the error code returned by this macro. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
Returns the number of whole objects that were read. Note that the number of objects actually read may be less than the number requested.
Comments
Do not use this macro to read data into a chunk, record or resource residing in a database—you must use the FileDmRead()
macro for such operations.
When the number of objects actually read is fewer than the number requested, you may be able to determine the cause of this result by examining the return value of the errP
parameter or by calling the FileGetLastError()
function. If the cause is insufficient data in the stream to satisfy the full request, the current stream position is at end-of-file and the "end of file" indicator is set. If a non-NULL
pointer was passed as the value of the errP
parameter when the FileRead()
function was called and an error was encountered, *
errP
holds a non-zero error code when the function returns. In addition, the FileError()
and FileEOF()
functions may be used to check for I/O errors.
See Also
FileReadLow Function
Purpose
Reads data from a file into a buffer or a data storage heap-based chunk (record or resource). Use the FileRead()
and FileDmRead()
macros instead of calling this function directly.
Declared In
FileStream.h
Prototype
int32_t FileReadLow ( FileHandstream
, void*baseP
, int32_toffset
, BooleandataStoreBased
, int32_tobjSize
, int32_tnumObj
, status_t*errP
)
Parameters
-
→ stream
- Handle to an open stream.
-
→ baseP
- Pointer to a buffer into which data is read
-
→ offset
- Offset into the
baseP
buffer marking the place at which the read data is stored. -
→ dataStoreBased
-
true
if the buffer is data-store based (that is, if it is a chunk, record or resource residing in a database) orfalse
if it is located in the dynamic heap. -
→ objSize
- Size of each stream object to read.
-
→ numObj
- Number of stream objects to read.
-
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
Returns the number of whole objects that were read. Note that the number of objects actually read may be less than the number requested.
Comments
Use the FileRead()
and FileDmRead()
macros instead of calling this function directly.
FileRewind Macro
Purpose
Reset position marker to beginning of stream and clear all error codes.
Declared In
FileStream.h
Prototype
#define FileRewind (
__stream__
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
See Also
FileSeek()
, FileTell()
, FileClearerr()
, FileEOF()
, FileError()
, FileGetLastError()
FileSeek Function
Purpose
Set current position within a file stream, extending the stream as necessary if it was opened with write access.
Declared In
FileStream.h
Prototype
status_t FileSeek ( FileHandstream
, int32_toffset
, FileOriginEnumorigin
)
Parameters
-
→ stream
- Handle to an open stream.
-
→ offset
- Position to set, expressed as the number of bytes from
origin
. This value may be positive, negative, or0
. -
→ origin
- Origin of the position change. Supply one of the values documented under "FileOriginEnum."
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
Comments
Attempting to seek beyond end-of-file in a read-only stream results in an I/O error.
This function's behavior is similar to that of the fseek
function provided by the C programming language runtime library.
See Also
FileTell Function
Purpose
Retrieves the current position and, optionally, the file size of a stream.
Declared In
FileStream.h
Prototype
int32_t FileTell ( FileHandstream
, int32_t*fileSizeP
, status_t*errP
)
Parameters
-
→ stream
- Handle to an open stream.
-
← fileSizeP
- Pointer to variable that receives the size of the stream in bytes. Pass
NULL
to ignore. -
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
If successful, returns the current position, expressed as an offset in bytes from the beginning of the stream. If an error was encountered, returns -1
.
Comments
The FileTell()
function can return the size of the input stream; as such, it provides some of the functionality of the standard C library stat
function. Note, however, that unlike the stat
function, FileTell()
requires that the file be open.
See Also
FileTruncate Function
Purpose
Truncate the file stream to a specified size.
Declared In
FileStream.h
Prototype
status_t FileTruncate ( FileHandstream
, int32_tnewSize
)
Parameters
Returns
Returns errNone
if no error, or a fileErr
code if an error occurs. See the section "File Stream Error Codes" for more information.
Comments
This function cannot be used on streams that are open in destructive read mode or read-only mode.
See Also
FileWrite Function
Purpose
Declared In
FileStream.h
Prototype
int32_t FileWrite ( FileHandstream
, const void*dataP
, int32_tobjSize
, int32_tnumObj
, status_t*errP
)
Parameters
-
→ stream
- Handle to an open stream.
-
→ dataP
- Pointer to a buffer holding the data to be written.
-
→ objSize
- Size of each stream object to write. Must be greater than or equal to
0
. -
→ numObj
- Number of stream objects to write.
-
← errP
- Pointer to a variable that is to hold the error code returned by this function. Pass
NULL
to ignore. See the section "File Stream Error Codes" for a list of error codes.
Returns
Returns the number of whole objects that were written. Note that the number of objects actually written may be less than the number requested. Should available storage be insufficient to satisfy the entire request, as much of the requested data as possible is written to the stream, which may result in the last object in the stream being incomplete.
Comments
Writing to files opened without write access or those that are in destructive read state is not allowed; thus, you cannot call the FileWrite()
, FileSeek()
, or FileTruncate()
functions on a stream that is in destructive read mode. One exception to this rule applies to streams that were opened in "write + append" mode and then switched into destructive read state. In this case, the FileWrite
function can append data to the stream, but it also preserves the current stream position so that subsequent reads pick up where they left off (you can think of this as a pseudo-pipe).