File System

Asynchronous access to the file system. More...

Data Structures
struct	uv_timespec_t
	Portable structure to hold time stamps. More...
struct	uv_stat_t
	Portable structure for file information. More...
struct	uv_dirent_t
	Directory entries. More...

Macros
#define	using_fs_scandir(scandir)
	Use a nodec_scandir_t in a scope. More...
#define	R_OK
	Permission mode for (user) reading.
#define	W_OK
	Permission mode for (user) writing.
#define	X_OK
	Permission mode for (user) execute.

Typedefs
typedef uv_fs_t	nodec_scandir_t
	Used to iterate over the contents of a directory.
typedef lh_value()	nodec_file_fun(uv_file file, const char *path, lh_value arg)
	Type of scoped file functions.
typedef struct _uv_file *	uv_file
	A platform independent file handle.

Enumerations
enum	nodec_open_flags_t {   UV_FS_O_APPEND, UV_FS_O_CREAT, UV_FS_O_EXCL, UV_FS_O_RANDOM,   UV_FS_O_RDONLY, UV_FS_O_RDWR, UV_FS_O_SEQUENTIAL, UV_FS_O_SHORT_LIVED,   UV_FS_O_TEMPORARY, UV_FS_O_TRUNC, UV_FS_O_WRONLY, UV_FS_O_DIRECT,   UV_FS_O_DIRECTORY, UV_FS_O_DSYNC, UV_FS_O_EXLOCK, UV_FS_O_NOATIME,   UV_FS_O_NOCTTY, UV_FS_O_NOFOLLOW, UV_FS_O_NONBLOCK, UV_FS_O_SYMLINK,   UV_FS_O_SYNC }
	File open modes, see open2(). More...
enum	uv_dirent_type_t {   UV_DIRENT_UNKNOWN, UV_DIRENT_FILE, UV_DIRENT_DIR, UV_DIRENT_LINK,   UV_DIRENT_FIFO, UV_DIRENT_SOCKET, UV_DIRENT_CHAR, UV_DIRENT_BLOCK }
	Directory entry types. More...

Functions
uv_errno_t	asyncx_fs_stat (const char *path, uv_stat_t *stat)
	Stat a file without raising an exception on failure. More...
uv_stat_t	async_fs_stat (const char *path)
	Stat a file. More...
uv_stat_t	async_fs_fstat (uv_file file)
	Stat a file handle. More...
uv_file	async_fs_open (const char *path, nodec_open_flags_t flags, int permissions)
	Open a file. More...
uv_errno_t	asyncx_fs_open (const char *path, nodec_open_flags_t flags, int permissions, uv_file *file)
	Open a file. More...
void	async_fs_close (uv_file file)
	Close a file. More...
size_t	async_fs_read_into (uv_file file, uv_buf_t buf, int64_t file_offset)
	Read a file into a buffer. More...
uv_buf_t	async_fs_read_buf (uv_file file, size_t max, int64_t file_offset)
	Read part of a file. More...
uv_buf_t	async_fs_read_buf_all (uv_file file, size_t max)
	Read an entire file (or up to max bytes) More...
nodec_scandir_t *	async_fs_scandir (const char *path)
	Initiate scanning a directory. More...
bool	async_fs_scandir_next (nodec_scandir_t *scanreq, uv_dirent_t *dirent)
	Iterate over the directory contents. More...
char *	async_fs_read_from (const char *path)
	Read full contents of a file as a string. More...
uv_buf_t	async_fs_read_buf_from (const char *path)
	Read full contents of a file as a buffer. More...
lh_value	using_async_fs_open (const char *path, nodec_open_flags_t flags, int permissions, nodec_file_fun *action, lh_value arg)
	Safely open a file, use it, and close it again. More...
uv_errno_t	using_asyncx_fs_open (const char *path, nodec_open_flags_t flags, int permissions, nodec_file_fun *action, lh_value arg, lh_value *result)
	Safely open a file, use it, and close it again. More...

Detailed Description

Asynchronous access to the file system.

---

Data Structure Documentation

uv_timespec_t

struct uv_timespec_t

Portable structure to hold time stamps.

Data Fields
long	tv_nsec	Nanoseconds.
long	tv_sec	Seconds since 1970-01-01UTC (Unix Epoch)

uv_stat_t

struct uv_stat_t

Portable structure for file information.

Data Fields
uv_timespec_t	st_atim	Last access time.
uv_timespec_t	st_birthtim	Creation time.
uint64_t	st_blksize	Block size used for I/O operations.
uint64_t	st_blocks	Blocks allocated for this file.
uv_timespec_t	st_ctim	Last time the file status changed.
uint64_t	st_dev	Device id of the file.
uint64_t	st_flags
uint64_t	st_gen
uint64_t	st_gid	Group ID associated with this file.
uint64_t	st_ino	INODE number of the file.
uint64_t	st_mode	File type and permission mode.
uv_timespec_t	st_mtim	Last modified time.
uint64_t	st_nlink	Number of hard links that point to this file.
uint64_t	st_rdev
uint64_t	st_size	Size of the file in bytes.
uint64_t	st_uid	User ID associated with this file.

uv_dirent_t

struct uv_dirent_t

Directory entries.

Data Fields
const char *	name	Name of the entry.
uv_dirent_type_t	type	Type of the entry.

Macro Definition Documentation

using_fs_scandir

#define using_fs_scandir

(

scandir

)

Use a nodec_scandir_t in a scope.

Parameters

scandir

A nodec_scandir_t returned from async_scandir()

Enumeration Type Documentation

nodec_open_flags_t

enum nodec_open_flags_t

File open modes, see open2().

The open mode must always include one of UV_FS_O_RDONLY, UV_FS_O_WRONLY, or UV_FS_O_RDWR.

Enumerator
UV_FS_O_APPEND	Open in append mode.
UV_FS_O_CREAT	Create a new file if it does not exist yet; mode specifies the permissions in this case.
UV_FS_O_EXCL	Fail if the file already exists.
UV_FS_O_RANDOM	Access is intended to be random.
UV_FS_O_RDONLY	Open for reading only.
UV_FS_O_RDWR	Open for reading and writing.
UV_FS_O_SEQUENTIAL	Access is intended to be sequential.
UV_FS_O_SHORT_LIVED	The file is intended to be short lived.
UV_FS_O_TEMPORARY	The file is intended as a temporary file and should not be flushed.
UV_FS_O_TRUNC	If the file exists and opened for writing, it is set to a zero length.
UV_FS_O_WRONLY	Open for writing only.
UV_FS_O_DIRECT	I/O is done directly from buffers that must be aligned.
UV_FS_O_DIRECTORY	If the path is not a directory, fail to open.
UV_FS_O_DSYNC	Writing is blocking and only completes if flushed to disk.
UV_FS_O_EXLOCK	Obtain an exclusive lock.
UV_FS_O_NOATIME	Do not update the access time of the file.
UV_FS_O_NOCTTY	If the path identifies a terminal device, opening the path will not cause that terminal to become the controlling terminal for the process (if the process does not already have one). (not supported on Windows)
UV_FS_O_NOFOLLOW	If the path is a symbolic link, fail to open. (not supported on Windows)
UV_FS_O_NONBLOCK	Open in non-blocking mode (not supported on Windows).
UV_FS_O_SYMLINK	If the path is not a symbolic link, fail to open. (not supported on Windows)
UV_FS_O_SYNC	The file is opened for synchronous I/O. Write operations will complete once all data and all metadata are flushed to disk.

uv_dirent_type_t

enum uv_dirent_type_t

Directory entry types.

Enumerator
UV_DIRENT_UNKNOWN	Unknown type.
UV_DIRENT_FILE	A regular file.
UV_DIRENT_DIR	A regular (sub)directory.
UV_DIRENT_LINK	A symbolic link.
UV_DIRENT_FIFO	A FIFO queue.
UV_DIRENT_SOCKET	A socket.
UV_DIRENT_CHAR	A character device.
UV_DIRENT_BLOCK	A block device.

Function Documentation

async_fs_close()

void async_fs_close

(

uv_file

file

)

Close a file.

Parameters

file	The file handle to be closed.

async_fs_fstat()

uv_stat_t async_fs_fstat

(

uv_file

file

)

Stat a file handle.

Parameters

file	The opened file handle.

Returns

The file information.

async_fs_open()

uv_file async_fs_open	(	const char *	path,
		nodec_open_flags_t	flags,
		int	permissions
	)

Open a file.

Parameters

path	The file path
flags	The file open flags.
mode	The file permissions mode if it is created (using UV_FS_O_CREAT).

Returns

The opened file handle on success.

async_fs_read_buf()

uv_buf_t async_fs_read_buf	(	uv_file	file,
		size_t	max,
		int64_t	file_offset
	)

Read part of a file.

Most efficient way to read files.

Parameters

file	The file to read from.
max	The maximum number of bytes to read.
file_offset	The offset to read from in the file.

Returns

a buffer contiaining the bytes read.

async_fs_read_buf_all()

uv_buf_t async_fs_read_buf_all	(	uv_file	file,
		size_t	max
	)

Read an entire file (or up to max bytes)

Parameters

file	The file to read from.
max	The maximum number of bytes to read.

Returns

A buffer with the file contents.

async_fs_read_buf_from()

uv_buf_t async_fs_read_buf_from

(

const char *

path

)

Read full contents of a file as a buffer.

Parameters

path	The file path

Returns

A heap allocated buffer containing the entire file contents.

async_fs_read_from()

char* async_fs_read_from

(

const char *

path

)

Read full contents of a file as a string.

Parameters

path	The file path.

Returns

The contents of the file as a string (assuming no 0 bytes)

async_fs_read_into()

size_t async_fs_read_into	(	uv_file	file,
		uv_buf_t	buf,
		int64_t	file_offset
	)

Read a file into a buffer.

Parameters

file	The file handle
buf	The buffer to read into.
file_offset	The offset to read from in the file.

Returns

The number of bytes read.

async_fs_scandir()

nodec_scandir_t* async_fs_scandir

(

const char *

path

)

Initiate scanning a directory.

Parameters

path	The directory path.

async_fs_scandir_next()

bool async_fs_scandir_next	(	nodec_scandir_t *	scanreq,
		uv_dirent_t *	dirent
	)

Iterate over the directory contents.

Parameters

[in,out]	scanreq	The iteration state.
[out]	dirent	The directory entry information if successful.

Returns

True while there are valid directory entries. Example:

nodec_scandir_t* scandir = async_scandir("/foo");
{using_scandir(scandir){
   uv_dirent_t dirent;
   while( async_scandir_next(scandir,&dirent) ) {
     printf("entry: %s\n", dirent.name);
   }
}}

async_fs_stat()

uv_stat_t async_fs_stat

(

const char *

path

)

Stat a file.

Parameters

path	The file path.

Returns

The file information.

asyncx_fs_open()

uv_errno_t asyncx_fs_open	(	const char *	path,
		nodec_open_flags_t	flags,
		int	permissions,
		uv_file *	file
	)

Open a file.

Returns an error code instead of throwing an exception.

Parameters

	path	The file path
	flags	The file open flags.
	mode	The file permissions mode if it is created (using UV_FS_O_CREAT).
[out]	file	Set to the file handle on success

Returns

A possible error code, or 0 on succes.

asyncx_fs_stat()

uv_errno_t asyncx_fs_stat	(	const char *	path,
		uv_stat_t *	stat
	)

Stat a file without raising an exception on failure.

Parameters

path	The file path.
stat	The result file information.

Returns

0 on success, and otherwise an error code (usually when the file does not exist).

using_async_fs_open()

lh_value using_async_fs_open	(	const char *	path,
		nodec_open_flags_t	flags,
		int	permissions,
		nodec_file_fun *	action,
		lh_value	arg
	)

Safely open a file, use it, and close it again.

Parameters

path	The file path
flags	The file open flags.
mode	The file permissions mode if it is created (using UV_FS_O_CREAT).
action	The file open action: called with the opened file handle.
arg	Extra argument passed to action.

Returns

The return value of action.

using_asyncx_fs_open()

uv_errno_t using_asyncx_fs_open	(	const char *	path,
		nodec_open_flags_t	flags,
		int	permissions,
		nodec_file_fun *	action,
		lh_value	arg,
		lh_value *	result
	)

Safely open a file, use it, and close it again.

Does not throw an exception on a file open error but returns an uv_errno_t instead.

Parameters

	path	The file path
	flags	The file open flags.
	mode	The file permissions mode if it is created (using UV_FS_O_CREAT).
	action	The file open action: called with the opened file handle.
	arg	Extra argument passed to action.
[out]	result	The return value of action.

Returns

A possible error code or 0 on success.