File POSIX API

Collaboration diagram for File POSIX API:

Functions
int	open (const char *file, int flags,...)
int	openat (int dirfd, const char *path, int flag,...)
int	creat (const char *path, mode_t mode)
int	close (int fd)
ssize_t	read (int fd, void *buf, size_t len)
ssize_t	write (int fd, const void *buf, size_t len)
off_t	lseek (int fd, off_t offset, int whence)
int	rename (const char *old_file, const char *new_file)
int	unlink (const char *pathname)
int	stat (const char *file, struct stat *buf)
int	fstat (int fildes, struct stat *buf)
int	fsync (int fildes)
int	fcntl (int fildes, int cmd,...)
int	ioctl (int fildes, int cmd,...)
int	ftruncate (int fd, off_t length)
int	statfs (const char *path, struct statfs *buf)
int	fstatfs (int fildes, struct statfs *buf)
int	mkdir (const char *path, mode_t mode)
int	rmdir (const char *pathname)
DIR *	opendir (const char *name)
struct dirent *	readdir (DIR *d)
long	telldir (DIR *d)
void	seekdir (DIR *d, long offset)
void	rewinddir (DIR *d)
int	closedir (DIR *d)
int	access (const char *path, int amode)
void	setcwd (char *buf)
char *	getcwd (char *buf, size_t size)
ssize_t	pread (int fd, void *buf, size_t len, off_t offset)
ssize_t	pwrite (int fd, const void *buf, size_t len, off_t offset)

Detailed Description

Function Documentation

open()

int open	(	const char *	file,
		int	flags,
			...
	)

this function is a POSIX compliant version, which will open a file and return a file descriptor according specified flags.

Parameters

file

the path name of file.

flags

the file open flags. Common values include: Access modes (mutually exclusive): O_RDONLY: Open for read-only access. O_WRONLY: Open for write-only access. O_RDWR: Open for both reading and writing. File status flags (can be combined with bitwise OR |): O_CREAT: Create the file if it does not exist. Requires a mode argument. O_TRUNC: Truncate the file to zero length if it already exists. O_APPEND: Append writes to the end of the file. O_EXCL: Ensure that O_CREAT creates the file exclusively. Other platform-specific flags

Returns

the non-negative integer on successful open, others for failed.

openat()

int openat	(	int	dirfd,
		const char *	path,
		int	flag,
			...
	)

Opens a file relative to a directory file descriptor.

Parameters

dirfd	The file descriptor of the directory to base the relative path on.
path	The path to the file to be opened, relative to the directory specified by dirfd. Can be an absolute path (in which case dirfd is ignored).
flag	File access and status flags (e.g., O_RDONLY, O_WRONLY, O_CREAT).

Returns

On success, returns a new file descriptor for the opened file. On failure, returns -1 and sets errno to indicate the error.

Note

When using relative paths, ensure dirfd is a valid directory descriptor. When pathname is absolute, the dirfd argument is ignored.

creat()

int creat	(	const char *	path,
		mode_t	mode
	)

this function is a POSIX compliant version, which will create a new file or rewrite an existing one

Parameters

path	the path name of file.
mode	the file permission bits to be used in creating the file (not used, can be 0)

Returns

the non-negative integer on successful open, others for failed.

close()

int close

(

int

fd

)

this function is a POSIX compliant version, which will close the open file descriptor.

Parameters

fd	the file descriptor.

Returns

0 on successful, -1 on failed.

read()

ssize_t read	(	int	fd,
		void *	buf,
		size_t	len
	)

this function is a POSIX compliant version, which will read specified data buffer length for an open file descriptor.

Parameters

fd	the file descriptor.
buf	the buffer to save the read data.
len	the maximal length of data buffer

Returns

the actual read data buffer length. If the returned value is 0, it may be reach the end of file, please check errno.

write()

ssize_t write	(	int	fd,
		const void *	buf,
		size_t	len
	)

this function is a POSIX compliant version, which will write specified data buffer length for an open file descriptor.

Parameters

fd	the file descriptor
buf	the data buffer to be written.
len	the data buffer length.

Returns

the actual written data buffer length.

lseek()

off_t lseek	(	int	fd,
		off_t	offset,
		int	whence
	)

this function is a POSIX compliant version, which will Reposition the file offset for an open file descriptor.

The lseek function sets the file offset for the file descriptor fd to a new value, determined by the offset and whence parameters. It can be used to seek to specific positions in a file for reading or writing.

Parameters

fd	the file descriptor.
offset	The offset, in bytes, to set the file position. The meaning of offset depends on the value of whence.
whence	the directive of seek. It can be one of: SEEK_SET: Set the offset to offset bytes from the beginning of the file. SEEK_CUR: Set the offset to its current location plus offset bytes. SEEK_END: Set the offset to the size of the file plus offset bytes.

Returns

the resulting read/write position in the file, or -1 on failed.

rename()

int rename	(	const char *	old_file,
		const char *	new_file
	)

this function is a POSIX compliant version, which will rename old file name to new file name.

Parameters

old_file	the old file name.
new_file	the new file name.

Returns

0 on successful, -1 on failed.

note: the old and new file name must be belong to a same file system.

unlink()

int unlink

(

const char *

pathname

)

this function is a POSIX compliant version, which will unlink (remove) a specified path file from file system.

Parameters

pathname

the specified path name to be unlinked.

Returns

0 on successful, -1 on failed.

stat()

int stat	(	const char *	file,
		struct stat *	buf
	)

this function is a POSIX compliant version, which will get file information.

Parameters

file	the file name
buf	the data buffer to save stat description.

Returns

0 on successful, -1 on failed.

fstat()

int fstat	(	int	fildes,
		struct stat *	buf
	)

this function is a POSIX compliant version, which will get file status.

Parameters

fildes	the file description
buf	the data buffer to save stat description.

Returns

0 on successful, -1 on failed.

fsync()

int fsync

(

int

fildes

)

this function is a POSIX compliant version, which shall request that all data for the open file descriptor named by fildes is to be transferred to the storage device associated with the file described by fildes.

Parameters

fildes

the file description

Returns

0 on successful completion. Otherwise, -1 shall be returned and errno set to indicate the error.

fcntl()

int fcntl	(	int	fildes,
		int	cmd,
			...
	)

this function is a POSIX compliant version, which shall perform a variety of control functions on devices.

Parameters

fildes	the file description
cmd	the specified command, Common values include: F_DUPFD: Duplicate a file descriptor. F_GETFD: Get the file descriptor flags. F_SETFD: Set the file descriptor flags. F_GETFL: Get the file status flags. F_SETFL: Set the file status flags.
...	represents the additional information that is needed by this specific device to perform the requested function. For example: When cmd is F_SETFL, an additional integer argument specifies the new status flags.

Returns

0 on successful completion. Otherwise, -1 shall be returned and errno set to indicate the error.

ioctl()

int ioctl	(	int	fildes,
		int	cmd,
			...
	)

this function is a POSIX compliant version, which shall perform a variety of control functions on devices.

Parameters

fildes	the file description
cmd	the specified command
...	represents the additional information that is needed by this specific device to perform the requested function.

Returns

0 on successful completion. Otherwise, -1 shall be returned and errno set to indicate the error.

ftruncate()

int ftruncate	(	int	fd,
		off_t	length
	)

this function is a POSIX compliant version, which cause the regular file referenced by fd to be truncated to a size of precisely length bytes.

Parameters

fd	the file descriptor.
length	the length to be truncated.

Returns

Upon successful completion, ftruncate() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.

statfs()

int statfs	(	const char *	path,
		struct statfs *	buf
	)

this function is a POSIX compliant version, which will return the information about a mounted file system.

Parameters

path	the path which mounted file system.
buf	the buffer to save the returned information.

Returns

0 on successful, others on failed.

fstatfs()

int fstatfs	(	int	fildes,
		struct statfs *	buf
	)

this function is a POSIX compliant version, which will return the information about a mounted file system.

Parameters

fildes	the file description.
buf	the buffer to save the returned information.

Returns

0 on successful, others on failed.

mkdir()

int mkdir	(	const char *	path,
		mode_t	mode
	)

this function is a POSIX compliant version, which will make a directory

Parameters

path	the directory path to be made.
mode	The permission mode for the new directory (unused here, can be set to 0).

Returns

0 on successful, others on failed.

rmdir()

int rmdir

(

const char *

pathname

)

this function is a POSIX compliant version, which will remove a directory.

Parameters

pathname

the path name to be removed.

Returns

0 on successful, others on failed.

opendir()

DIR* opendir

(

const char *

name

)

this function is a POSIX compliant version, which will open a directory.

Parameters

name	the path name to be open.

Returns

the DIR pointer of directory, NULL on open directory failed.

readdir()

struct dirent* readdir

(

DIR *

d

)

this function is a POSIX compliant version, which will return a pointer to a dirent structure representing the next directory entry in the directory stream.

Parameters

d	the directory stream pointer.

Returns

the next directory entry, NULL on the end of directory or failed.

telldir()

long telldir

(

DIR *

d

)

this function is a POSIX compliant version, which will return current location in directory stream.

Parameters

d	the directory stream pointer.

Returns

the current location in directory stream.

seekdir()

void seekdir	(	DIR *	d,
		long	offset
	)

this function is a POSIX compliant version, which will set position of next directory structure in the directory stream.

Parameters

d	the directory stream.
offset	the offset in directory stream.

rewinddir()

void rewinddir

(

DIR *

d

)

this function is a POSIX compliant version, which will reset directory stream.

Parameters

d	the directory stream.

closedir()

int closedir

(

DIR *

d

)

this function is a POSIX compliant version, which will close a directory stream.

Parameters

d	the directory stream.

Returns

0 on successful, -1 on failed.

access()

int access	(	const char *	path,
		int	amode
	)

this function is a POSIX compliant version, which shall check the file named by the pathname pointed to by the path argument for accessibility according to the bit pattern contained in amode.

Parameters

path	the specified file/dir path.
amode	the value is either the bitwise-inclusive OR of the access permissions to be checked (R_OK, W_OK, X_OK) or the existence test (F_OK).

setcwd()

void setcwd

(

char *

buf

)

this function is a POSIX compliant version, which will set current working directory.

Parameters

buf	the current directory.

getcwd()

char* getcwd	(	char *	buf,
		size_t	size
	)

this function is a POSIX compliant version, which will return current working directory.

Parameters

buf	the returned current directory.
size	the buffer size.

Returns

the returned current directory.

pread()

ssize_t pread	(	int	fd,
		void *	buf,
		size_t	len,
		off_t	offset
	)

this function is a POSIX compliant version, which will read specified data buffer length for an open file descriptor.

Parameters

fd	the file descriptor.
buf	the buffer to save the read data.
len	the maximal length of data buffer
offset	the file pos

Returns

the actual read data buffer length. If the returned value is 0, it may be reach the end of file, please check errno.

pwrite()

ssize_t pwrite	(	int	fd,
		const void *	buf,
		size_t	len,
		off_t	offset
	)

this function is a POSIX compliant version, which will write specified data buffer length for an open file descriptor.

Parameters

fd	the file descriptor
buf	the data buffer to be written.
len	the data buffer length.
offset	the file pos

Returns

the actual written data buffer length.