Xvfs

異なるファイルシステムを共通のインターフェースで操作するための抽象化層です [詳解]

Xvfs 連携図

マクロ定義
#define	X_VFS_TAG   (X_MAKE_TAG('X', 'V', 'I', 'F'))

関数
XError	xvfs_chdir (XVirtualFs *vfs, const char *path)
	カレントディレクトリを変更します [詳解]
XError	xvfs_close (XFile *fp)
	ファイルをクローズします [詳解]
XError	xvfs_closedir (XDir *dir)
	ディレクトリをクローズします [詳解]
XError	xvfs_copyfile (XVirtualFs *vfs, const char *src, const char *dst)
	ファイルをコピーします [詳解]
XError	xvfs_copyfile2 (XFile *src, XFile *dst)
	ファイルをコピーします [詳解]
XError	xvfs_copytree (XVirtualFs *vfs, const char *src, const char *dst)
	ディレクトリツリーをコピーします [詳解]
XError	xvfs_exists (XVirtualFs *vfs, const char *path, bool *exists)
	パスが存在するかどうかを判定します [詳解]
XError	xvfs_flush (XFile *fp)
	バッファされたデータを出力します [詳解]
int	xvfs_getc (XFile *fp)
	ファイルから1文字を読み込みます
XError	xvfs_getcwd (XVirtualFs *vfs, char *buf, size_t size)
	カレントディレクトリを取得します [詳解]
XError	xvfs_gets (XFile *fp, char *dst, size_t size, char **result, bool *overflow)
	ファイルから1行を読み込みます [詳解]
XStream *	xvfs_init_stream (XStream *stream, XFile *fp)
XError	xvfs_is_directory (XVirtualFs *vfs, const char *path, bool *isdir)
	パスがディレクトリかどうかを判定します [詳解]
XError	xvfs_is_regular (XVirtualFs *vfs, const char *path, bool *isreg)
	パスが通常ファイルかどうかを判定します [詳解]
XError	xvfs_makedirs (XVirtualFs *vfs, const char *path, bool exist_ok)
	ディレクトリを作成します [詳解]
XError	xvfs_mkdir (XVirtualFs *vfs, const char *path)
	ディレクトリを作成します [詳解]
XError	xvfs_open (XVirtualFs *vfs, const char *path, XOpenMode mode, XFile **o_fp)
	ファイルをオープンします [詳解]
XError	xvfs_opendir (XVirtualFs *vfs, const char *path, XDir **o_dir)
	ディレクトリをオープンします [詳解]
int	xvfs_printf (XFile *fp, const char *fmt,...)
	ファイルにprintf形式で文字列を書き込みます
int	xvfs_putc (XFile *fp, int c)
	ファイルに1文字を書き込みます
int	xvfs_puts (XFile *fp, const char *str)
	ファイルに文字列を書き込みます
XError	xvfs_read (XFile *fp, void *dst, size_t size, size_t *nread)
	ファイルからデータを読み込みます [詳解]
XError	xvfs_readdir (XDir *dir, XDirEnt *dirent, XDirEnt **result)
	ディレクトリから要素を読み込みます [詳解]
XError	xvfs_remove (XVirtualFs *vfs, const char *path)
	エントリを削除します [詳解]
XError	xvfs_rename (XVirtualFs *vfs, const char *oldpath, const char *newpath)
	エントリの名前や位置を変更します [詳解]
XError	xvfs_rmtree (XVirtualFs *vfs, const char *path)
	ディレクトリツリーを削除します [詳解]
XError	xvfs_seek (XFile *fp, XOffset pos, XSeekMode whence)
	ファイル位置を変更します [詳解]
XError	xvfs_stat (XVirtualFs *vfs, const char *path, XStat *statbuf)
	エントリの状態を取得します [詳解]
XError	xvfs_tell (XFile *fp, XSize *pos)
	ファイル位置を取得します [詳解]
XError	xvfs_utime (XVirtualFs *vfs, const char *path, XTime time)
	エントリのタイムスタンプを変更します [詳解]
int	xvfs_vprintf (XFile *fp, const char *fmt, va_list args)
	ファイルにvprintf形式で文字列を書き込みます
XError	xvfs_walktree (XVirtualFs *vfs, const char *path, XFsTreeWalker walker, void *userptr)
	ディレクトリツリーを走査します [詳解]
XError	xvfs_write (XFile *fp, const void *src, size_t size, size_t *nwritten)
	ファイルにデータを書き込みます [詳解]

詳解

異なるファイルシステムを共通のインターフェースで操作するための抽象化層です

LinuxやWindowsではfopen()等の標準のファイル操作APIの下位実装にファイルシステ ムの違いを隠蔽する抽象化層が存在しているため、ユーザーアプリケーションからは 、アプリケーションからはファイルシステムの違いを意識せず扱うことができます。

しかし、特定のランタイムライブラリを持たない小規模な組込みシステムでは、ファ イルシステムドライバ(FatFs等)は抽象化層なしで直接使用できるように実装されま す。

これらのドライバをpicoxが定義する仮想ファイルシステムインターフェースにに合 わせてラップすることで、特定のファイルシステムに依存しない共通のファイル操作 を実現します。

関数詳解

XError xvfs_chdir	(	XVirtualFs *	vfs,
		const char *	path
	)

カレントディレクトリを変更します

事前条件

+path != NULL

XError xvfs_close

(

XFile *

fp

)

ファイルをクローズします

クローズされたXFileオブジェクトは無効となり、以降のあらゆる操作は不正となります。 クローズに失敗した場合も、無効となるため、書き込みを行ったファイルはクローズ の前に明示的にフラッシュを行ったほうがエラー処理を行いやすいです。

fpがNULLを指す場合は何も処理をせずに正常終了を返します。

XError xvfs_closedir

(

XDir *

dir

)

ディレクトリをクローズします

クローズされたディレクトリは無効となり、以降のあらゆる操作は不正となります。

dirがNULLを指す場合は何も処理をせずに正常終了を返します。

XError xvfs_copyfile	(	XVirtualFs *	vfs,
		const char *	src,
		const char *	dst
	)

ファイルをコピーします

事前条件

• src != NULL
• dst != NULL

srcからdstにコピーを行います。

XError xvfs_copyfile2	(	XFile *	src,
		XFile *	dst
	)

ファイルをコピーします

事前条件

• src != NULL
• dst != NULL

srcからdstにコピーを行います。

XError xvfs_copytree	(	XVirtualFs *	vfs,
		const char *	src,
		const char *	dst
	)

ディレクトリツリーをコピーします

事前条件

• src != NULL
• dst != NULL

dstが示すターゲットディレクトリは、既存のもので無い必要があります。

失敗した場合でも、途中で作成されたファイルはそのまま残ります。

XError xvfs_exists	(	XVirtualFs *	vfs,
		const char *	path,
		bool *	exists
	)

パスが存在するかどうかを判定します

事前条件

• path != NULL

XError xvfs_flush

(

XFile *

fp

)

バッファされたデータを出力します

事前条件

• fp != NULL

ファイルシステムの実装次第ですが、通常はIOアクセスを減らすために、writeされ たデータはある程度メモリ上にバッファリングされます。

ファイルへの書き込みを確実にしたいタイミングではこの関数でバッファリングを強 制的にフラッシュしてください。

クローズやシークの際には暗黙的にフラッシュが呼び出されます。

XError xvfs_getcwd	(	XVirtualFs *	vfs,
		char *	buf,
		size_t	size
	)

カレントディレクトリを取得します

事前条件

• buf != NULL

カレントディレクトリパスがsizeバイトに収まらない場合はエラーとなります。

XError xvfs_gets	(	XFile *	fp,
		char *	dst,
		size_t	size,
		char **	result,
		bool *	overflow
	)

ファイルから1行を読み込みます

参照

xstream_gets

XStream* xvfs_init_stream	(	XStream *	stream,
		XFile *	fp
	)

ストリームをファイルストリームとして初期化します

XError xvfs_is_directory	(	XVirtualFs *	vfs,
		const char *	path,
		bool *	isdir
	)

パスがディレクトリかどうかを判定します

事前条件

• path != NULL

XError xvfs_is_regular	(	XVirtualFs *	vfs,
		const char *	path,
		bool *	isreg
	)

パスが通常ファイルかどうかを判定します

事前条件

• path != NULL

XError xvfs_makedirs	(	XVirtualFs *	vfs,
		const char *	path,
		bool	exist_ok
	)

ディレクトリを作成します

事前条件

• path != NULL

パスの末端のディレクトリを作成するために必要な中間のディレクトリも含めて作成 します。

exist_ok == trueの場合は、末端のディレクトリが既に存在していた場合も正常終 了を返します。

XError xvfs_mkdir	(	XVirtualFs *	vfs,
		const char *	path
	)

ディレクトリを作成します

事前条件

• path != NULL

pathが示すディレクトリの作成を試みます。

XError xvfs_open	(	XVirtualFs *	vfs,
		const char *	path,
		XOpenMode	mode,
		XFile **	o_fp
	)

ファイルをオープンします

事前条件

• path != NULL
• o_fp != NULL

pathが示すファイルをオープンし、そのポインタを*o_fpにセットします。失敗した 場合は、*o_fpにはNULLがセットされます。

XError xvfs_opendir	(	XVirtualFs *	vfs,
		const char *	path,
		XDir **	o_dir
	)

ディレクトリをオープンします

事前条件

• path != NULL
• o_dir != NULL

pathが示すディレクトリをオープンし、そのポインタを*o_dirにセットします。 失敗した場合は、*o_dirにはNULLがセットされます。

XError xvfs_read	(	XFile *	fp,
		void *	dst,
		size_t	size,
		size_t *	nread
	)

ファイルからデータを読み込みます

事前条件

• fp != NULL
• dst != NULL

dstにsizeバイトの読み込みを試み、nreadがNULLでなければ、読み込みに成功したバ イト数を格納します。

関数が正常に終了し、size != *nreadであった場合は、ファイル終端に達したことを 意味します。

XError xvfs_readdir	(	XDir *	dir,
		XDirEnt *	dirent,
		XDirEnt **	result
	)

ディレクトリから要素を読み込みます

事前条件

• dir != NULL
• dirent != NULL
• result != NULL

読み込みはdirentが指す領域に行われ、読み込みに成功すると、*resultにはdirent が格納されます。

XError xvfs_remove	(	XVirtualFs *	vfs,
		const char *	path
	)

エントリを削除します

事前条件

• path != NULL

パスが示すエントリをファイルシステムから削除します。

XError xvfs_rename	(	XVirtualFs *	vfs,
		const char *	oldpath,
		const char *	newpath
	)

エントリの名前や位置を変更します

事前条件

• oldpath != NULL
• newpath != NULL

oldpathが示すエントリをnewpathに移動します。

覚え書き

ファイルシステムにとって名前や位置の変更は、通常はコストの低い処理ですが、 xunionfs_rename()で移動がファイルシステムをまたがる場合、ファイルをコピーし 、元ファイルを削除するという処理が行われます。思わぬ高負荷の要因となることが あるため注意しましょう。

XError xvfs_rmtree	(	XVirtualFs *	vfs,
		const char *	path
	)

ディレクトリツリーを削除します

事前条件

• path != NULL

失敗した場合でも、途中で削除されたファイルは元にはもどりません。

XError xvfs_seek	(	XFile *	fp,
		XOffset	pos,
		XSeekMode	whence
	)

ファイル位置を変更します

事前条件

• fp != NULL

新たな位置はwhenceで指定された位置にoffsetバイトを加えることによって与えられ ます。

ファイル位置が0未満となる場合はエラーを返しますが、ファイルサイズを越える位 置へのシークは有効です。

ファイルサイズを超えた位置に書き込むを行うと、空き空間は不定のデータで埋めら れます。

XError xvfs_stat	(	XVirtualFs *	vfs,
		const char *	path,
		XStat *	statbuf
	)

エントリの状態を取得します

事前条件

• path != NULL
• statbuf != NULL

パスが示すエントリの状態を*statbufに格納します。

XError xvfs_tell	(	XFile *	fp,
		XSize *	pos
	)

ファイル位置を取得します

事前条件

• fp != NULL
• pos != NULL

read, write, seek等で移動するファイル位置の現在値をposに格納します。

XError xvfs_utime	(	XVirtualFs *	vfs,
		const char *	path,
		XTime	time
	)

エントリのタイムスタンプを変更します

事前条件

• path != NULL

パスが示すエントリのタイムスタンプをtimeに変更します

XError xvfs_walktree	(	XVirtualFs *	vfs,
		const char *	path,
		XFsTreeWalker	walker,
		void *	userptr
	)

ディレクトリツリーを走査します

事前条件

• path != NULL
• walker != NULL

パスが示すディレクトリを再帰的にたどり、各エントリに対してwalker()を呼び出し ます。

XError xvfs_write	(	XFile *	fp,
		const void *	src,
		size_t	size,
		size_t *	nwritten
	)

ファイルにデータを書き込みます

事前条件

• fp != NULL
• src != NULL

srcからファイルにsizeバイトの書き込みを試み、nwrittenがNULLでなければ、書き 込みに成功したバイト数を格納します。