file system2.txt

Linux C 语言函数

creat and open

SYNOPSIS
int open(const char *path, int flags); 

int open(const char *path, int flags, mode_t mode); 

int creat(const char *path, mode_t mode); 


PARAMETERS
path: [in] the path of the new file to create. 

mode: [in] the new permission mask of the file. It is masked by the umask value: 
	(mode & ~umask). 

flags: [in] flags (see description). 


DESCRIPTION
open opens an file. The flags parameter must be one of the following: 


O_RDONLY 
the file is opened for reading. 

O_WRONLY 
the file is opened for writing. 

O_RDWR 
the file is opened for both reading and writing. 
The following values may be or'ed together and with one of the preceding values: 


O_CREAT 
create the file if it does not exist. 

O_EXCL 
used with O_CREAT, if the file exists, the call fails. The test for existence and the 
creation if the file does not exists is atomic operation according to POSIX.1. 

O_NOCTTY 
the file will not become the controly tty of the task even if the file is a tty and the 
task does not have a controling terminal. 

O_TRUNC 
if the file already exists, truncate its lenght to 0. 

O_APPEND 
the file is opened for appending. The file pointer is always at the end of the file. 

O_NONBLOCK or O_NDELAY 
the calls manipulating the file never block. 

O_SYNC 
the file buffers are always synchronized with the on disk file. The write calls block until
 the data is completely written on disk. This is not POSIX.1. 
create creates a new file. The new file is open for writing only. If a file with the same 
path already existed, then it is trucated. 

RETURN VALUE
On success, a file descriptor for the file is returned. This file descriptor is the lowest 
numbered unused descriptor. On error, those calls return -1, and errno is set to one of the
following values. 


EISDIR: the last component of the path is a directory. 
ETXTBSY: tried to create an already used executable. 
EFAULT, EACCESS, ENAMETOOLONG, ENOENT, ENOTDIR, EMFILE, ENFILE, ENOMEM, EROFS, ELOOP, 
EEXIST or ENOSPC.


****************************************************************************************
dup and dup2

SYNOPSIS
int dup(int oldfd); 

int dup2(int oldfd, int newfd); 


PARAMETERS
oldfd: [in] the file descriptor to copy. 

newfd: [in] the file descriptor to copy to. 


DESCRIPTION
dup duplicates a file descriptor to the lowest unused file descriptor available. dup2 
duplicates a file descriptor to another specified file descriptor. If the destination file 
descriptor is already used, it is closed. The two descriptors share all (ie. file locks, 
position, etc.) but the close-on-exec flag. 


RETURN VALUE
The call returns the new descriptor on success. It returns -1 on error and sets errno to one
of the following values: EBADF or EMFILE. 

NOTE: EINVAL might well be added to the set of possible errors in the future. 
(Take a look in the kernel source.)



****************************************************************************************
fcntl

SYNOPSIS
int fcntl(int fd, int cmd); 

int fcntl(int fd, int cmd, long arg); 


PARAMETERS
fd: [in] the file descriptor affected by the call. 

cmd: [in] the operation to apply on the file descriptor. 

arg: [in] an optionnal argument to the operation. 


DESCRIPTION
This call directly applies an operation on a file descriptor. The possible operations are: 

F_DUPFD 
Duplicates fd the the new file descriptor specified by arg. If arg specifies a file 
descriptor that was already opened, then the file descriptor is first closed. It has the 
same effect has dup2. See section dup and dup2 

F_GETFD 
Returns the close-on-exec flag of fd. 

F_SETFD 
Sets the close-on-exec flag of fd. 

F_GETFL 
Returns the file descriptor flags (as specified by open). 

F_SETFL 
Sets the file descriptor flags to arg. The only flags that can be modified are O_APPEND and
O_NONBLOCK. See section creat and open 

F_GETLK 
Determine if the lock described by arg can be set on the file. If so, the l_type member is 
set to F_UNLCK. Otherwise, arg is modified to describe the lock preventing the set operation
. 
F_SETLK 
Set the lock described by arg on the file or release an already existing lock. 

F_SETLKW 
Same as F_SETLK but block if the lock can not be set. 

F_GETOWN 
Returns the process id or the process group of a socket. A process group is returned as a 
negative value. 

F_SETOWN 
Sets the process id or the process group that owns a socket. The owner of the socket 
receives the SIGIO and SIGURG signals. A process group is specified by a negative value. 
When using the F_GETLK, F_SETLK or F_SETLKW commands, the argument is a pointer to a flock 
structure. This structure has the following layout: 

struct flock {
    short l_type;   /* read, write or unlock */
    short l_whence; /* how to interpret l_start */
    off_t l_start;  /* where to begin the locking area */
    off_t l_len;    /* the lenght of the area to lock */
    pid_t l_pid;    /* the pid of the task holding the lock:
                       returned by F_GETLK */
};

The l_whence member has the same meaning as for lseek. See section lseek l_type can take one
of the following values: 


F_RDLCK 
for a shared read lock on. 

F_WRLCK 
for an exclusive write lock. 

F_UNLCK 
to unlock the region. 
The system merges adjacent locking regions of the same type and owned by the same task. When
a subregion inside a region is unlocked, the region is split in two parts. 


RETURN VALUE
On success, it depends on the cmd parameter: 


F_DUPFD 
the new file descriptor. 

F_GETFD 
the value of the close-on-exec flag. 

F_GETFL 
the value of the file descriptor flags. 

F_GETOWN 
the owner of the file descriptor. 

On error, the call returns -1 and errno is set to one of the following values: 


EINVAL: for F_DUPFD, arg is invalid or the maximum number of opened file descriptor is 
reached. For F_GETLK, specified a lock with F_UNLCK. Or unlock operation failed. 
EBADF: the file descriptor is invalid, or the task requested a lock for reading or writing 
while it does not have the corresponding read or write access right on the file. 
EAGAIN: impossible to set the lock. 
ENOLCK: impossible to allocate memory for the new lock. 
EFAULT, ERESTARTSYS.



****************************************************************************************
fstat, stat and lstat

SYNOPSIS
int fstat(int fd, struct stat *buf); 

int stat(char *path, struct stat *buf); 

int lstat(char *path, struct stat *buf); 


PARAMETERS
fd: [in] the file descriptor we want to get the information from. 

path: [in] the file path we want to get the information from. 

buf: [out] points to the buffer that will contain the information. 


DESCRIPTION
Those calls return a stat structure in buf with the following format: 


struct stat {
        dev_t           st_dev;       /* device */
        unsigned short  __pad1;       /* padding */
        ino_t           st_ino;       /* inode
        umode_t         st_mode;      /* access mode */
        nlink_t         st_nlink;     /* number of hard links */
        uid_t           st_uid;       /* uid */
        gid_t           st_gid;       /* gid */
        dev_t           st_rdev;      /* device type */
        unsigned short  __pad2;       /* padding */
        off_t           st_size;      /* size (in bytes) */
        unsigned long   st_blksize;   /* block size */
        unsigned long   st_blocks;    /* number of allocated blocks */
        time_t          st_atime;     /* last access time */
        unsigned long   __unused1;    /* unused */
        time_t          st_mtime;     /* last modification time */
        unsigned long   __unused2;    /* unused */
        time_t          st_ctime;     /* last change time */
        unsigned long   __unused3;    /* unused */
        unsigned long   __unused4;    /* unused */
        unsigned long   __unused5;    /* unused */
};

The change time is for modifications to the inode, whereas the modification time is for 
modifications to the content of the file. 

fstat gets the information from a file descriptor. stat and lstat get the information from 
a file path. However, lstat used on a link will give get the information from the link 
itself instead of the file pointed by the link. 

Note: the kernel contains a older stats functions. However, it would seem they are no longer
used. (Maybe only by very old binaries.) 


RETURN VALUE
On success zero is returned. On error, -1 is returned and errno is set to one of the 
following values: 

for stat or lstat: 

EFAULT, ENAMETOOLONG, ENOMEM, ENOENT, ENOTDIR, EACCESS. 

for fstat: 

EBADFS, EFAULT 

****************************************************************************************
fstatfs and statfs

SYNOPSIS
int fstatfs(int fd, struct statfs *buf); 

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


PARAMETERS
fd: [in] the file descriptor we want to get the information from. 

path: [in] the file path we want to get the information from. 

buf: [out] points to the buffer that will contain the information. 


DESCRIPTION
Those calls return information about the file systems on which the files fd or path resides.
The buffer has the following format: 


struct statfs {
        long f_type;       /* file system type */
        long f_bsize;      /* block size */
        long f_blocks;     /* total number of blocks */
        long f_bfree;      /* total number of free blocks */
        long f_bavail;     /* number of free blocks for normal user */
        long f_files;      /* number of file nodes */
        long f_ffree;      /* number of free file nodes */
        fsid_t f_fsid;     /* file system id */
        long f_namelen;    /* maximum file name length */
        long f_spare[6];   /* unused */
};


RETURN VALUE
On success zero is returned. On error, -1 is returned and errno is set to one of the 
following values: 

In the case of fstatfs: 

EBADFS, EFAULT, ENOSYS or EIO. 

In the case of statfs: 

EINVAL: path contains a caracter outside the ASCII 0-127 range. 
ENOTDIR, ENAMETOOLONG, ENOENT, EACCESS, ELOOP, EFAULT, ENOSYS or EIO.