Standard I/O functions

Detailed Description

The BaFile API specifies a number of standard I/O functions for working with files.

The BaFile API is used by some of the examples in the example directory. The BaFile API is not used by any of the web-server code.

The BaFile API provides functions similar to standard ANSI I/O functions.

Collaboration diagram for Standard I/O functions:

Functions
BA_API DirIntfPtr	baOpenDir (const char *dirname, int *status, const char **ecode)
	Open a directory through the platform's default DiskIo. More...
BA_API int	baCloseDir (DirIntfPtr *dirIntf)
	Close a directory iterator. More...
BA_API int	baStat (const char *name, IoStat *st)
	Read file or directory metadata. More...
BA_API ResIntfPtr	baOpenRes (const char *name, U32 mode, int *status, const char **ecode)
	Open a binary file for reading or writing. More...
BA_API int	baCloseRes (ResIntfPtr *fp)
	Close a resource handle, including when the underlying close reports failure. More...
BA_API int	baMkDir (const char *dname, const char **ecode)
	Create a directory. More...
BA_API int	baRmdDir (const char *dname, const char **ecode)
	Remove an empty directory. More...
BA_API int	baRemove (const char *fname, const char **ecode)
	Remove a file. More...
BA_API int	baRename (const char *from, const char *to, const char **ecode)
	Rename a file or directory. More...

Function Documentation

baCloseDir()

BA_API int baCloseDir

(

DirIntfPtr *

dirIntf

)

Close a directory iterator.

Parameters

[in,out]

dirIntf

Required pointer to a live iterator returned by baOpenDir. The iterator is released and *dirIntf is set to NULL.

Returns

Zero on success, otherwise an IOINTF error code.

baCloseRes()

BA_API int baCloseRes

(

ResIntfPtr *

fp

)

Close a resource handle, including when the underlying close reports failure.

Parameters

[in,out]

fp

Required pointer to a live handle returned by baOpenRes. The handle is consumed and *fp is set to NULL; do not retry with that handle.

Returns

Zero on success, otherwise the resource's close error code.

baMkDir()

BA_API int baMkDir	(	const char *	dname,
		const char **	ecode
	)

Create a directory.

Parameters

[in]	dname	NUL-terminated directory path.
[out]	ecode	Optional borrowed platform error description on failure; may be NULL. Do not free it.

Returns

Zero on success, otherwise an IOINTF error code.

baOpenDir()

BA_API DirIntfPtr baOpenDir	(	const char *	dirname,
		int *	status,
		const char **	ecode
	)

Open a directory through the platform's default DiskIo.

Parameters

[in]	dirname	NUL-terminated directory path. Path syntax and the starting directory depend on the selected platform implementation.
[out]	status	Required status pointer: zero on success, otherwise an IOINTF error code.
[out]	ecode	Optional pointer for a borrowed platform error description; may be NULL. Inspect it only on failure; do not free the returned string.

Returns

Owned directory iterator, or NULL on failure. Close it with baCloseDir. Entries may include '.' and '..' on some platforms.

baOpenRes()

BA_API ResIntfPtr baOpenRes	(	const char *	name,
		U32	mode,
		int *	status,
		const char **	ecode
	)

Open a binary file for reading or writing.

Parameters

[in]	name	NUL-terminated path using the platform's default DiskIo.
[in]	mode	OpenRes_READ, OpenRes_WRITE or a supported combination with OpenRes_APPEND. See IoIntf_OpenRes for the mode table and portability limits. Write mode without append can truncate an existing file.
[out]	status	Required status pointer: zero on success, otherwise an IOINTF error code.
[out]	ecode	Optional pointer for a borrowed platform error description; may be NULL. Inspect only on failure and do not free it.

Returns

Owned resource handle, or NULL on failure. Close it with baCloseRes.

baRemove()

BA_API int baRemove	(	const char *	fname,
		const char **	ecode
	)

Remove a file.

Parameters

[in]	fname	NUL-terminated file path.
[out]	ecode	Optional borrowed platform error description on failure; may be NULL. Do not free it.

Returns

Zero on success, otherwise an IOINTF error code.

baRename()

BA_API int baRename	(	const char *	from,
		const char *	to,
		const char **	ecode
	)

Rename a file or directory.

Parameters

[in]	from	NUL-terminated existing path.
[in]	to	NUL-terminated destination path. Replacement and cross-device behavior depend on the platform's DiskIo implementation.
[out]	ecode	Optional borrowed platform error description on failure; may be NULL. Do not free it.

Returns

Zero on success, otherwise an IOINTF error code.

baRmdDir()

BA_API int baRmdDir	(	const char *	dname,
		const char **	ecode
	)

Remove an empty directory.

Parameters

[in]	dname	NUL-terminated directory path.
[out]	ecode	Optional borrowed platform error description on failure; may be NULL. Do not free it.

Returns

Zero on success, otherwise an IOINTF error code.

baStat()

BA_API int baStat	(	const char *	name,
		IoStat *	st
	)

Read file or directory metadata.

Parameters

[in]	name	NUL-terminated path using the platform's default DiskIo.
[out]	st	Required metadata buffer, valid only on success.

Returns

Zero on success, otherwise an IOINTF error code.