When you issue an ls -l shell command on a file, it gives you information about the size of the file, who owns it, when it was last modified, etc. These are called the file attributes, and are associated with the file itself and not a particular one of its names.
This section contains information about how you can inquire about and modify the attributes of a file.
When you read the attributes of a file, they come back in a structure called struct stat. This section describes the names of the attributes, their data types, and what they mean. For the functions to read the attributes of a file, see the section called “Reading the Attributes of a File”.
The header file sys/stat.h declares all the symbols defined in this section. function>struct stat/function> The stat structure type is used to return information about the attributes of a file. It contains at least the following members:
Specifies the mode of the file. This includes file type information (the section called “Testing the Type of a File”) and the file permission bits (the section called “The Mode Bits for Access Permission”).
The file serial number, which distinguishes this file from all other files on the same device.
Identifies the device containing the file. The st_ino and st_dev, taken together, uniquely identify the file. The st_dev value is not necessarily consistent across reboots or system crashes, however.
The number of hard links to the file. This count keeps track of how many directories have entries for this file. If the count is ever decremented to zero, then the file itself is discarded as soon as no process still holds it open. Symbolic links are not counted in the total.
The user ID of the file's owner. the section called “File Owner”.
The group ID of the file. the section called “File Owner”.
This specifies the size of a regular file in bytes. For files that are really devices this field isn't usually meaningful. For symbolic links this specifies the length of the file name the link refers to.
This is the last access time for the file. the section called “File Times”.
This is the fractional part of the last access time for the file. the section called “File Times”.
This is the time of the last modification to the contents of the file. the section called “File Times”.
This is the fractional part of the time of the last modification to the contents of the file. the section called “File Times”.
This is the time of the last modification to the attributes of the file. the section called “File Times”.
This is the fractional part of the time of the last modification to the attributes of the file. the section called “File Times”.
This is the amount of disk space that the file occupies, measured in units of 512-byte blocks.
The number of disk blocks is not strictly proportional to the size of the file, for two reasons: the file system may use some blocks for internal record keeping; and the file may be sparse--it may have "holes" which contain zeros but do not actually take up space on the disk.
You can tell (approximately) whether a file is sparse by comparing this value with st_size, like this:
(st.st_blocks * 512 st.st_size)
This test is not perfect because a file that is just slightly sparse might not be detected as sparse at all. For practical applications, this is not a problem.
The optimal block size for reading of writing this file, in bytes. You might use this size for allocating the buffer space for reading of writing the file. (This is unrelated to st_blocks.)
The extensions for the Large File Support (LFS) require, even on 32-bit machines, types which can handle file sizes up to 2^63. Therefore a new definition of struct stat is necessary.
function>struct stat64/function> The members of this type are the same and have the same names as those in struct stat. The only difference is that the members st_ino, st_size, and st_blocks have a different type to support larger values.
Specifies the mode of the file. This includes file type information (the section called “Testing the Type of a File”) and the file permission bits (the section called “The Mode Bits for Access Permission”).
The file serial number, which distinguishes this file from all other files on the same device.
Identifies the device containing the file. The st_ino and st_dev, taken together, uniquely identify the file. The st_dev value is not necessarily consistent across reboots or system crashes, however.
The number of hard links to the file. This count keeps track of how many directories have entries for this file. If the count is ever decremented to zero, then the file itself is discarded as soon as no process still holds it open. Symbolic links are not counted in the total.
The user ID of the file's owner. the section called “File Owner”.
The group ID of the file. the section called “File Owner”.
This specifies the size of a regular file in bytes. For files that are really devices this field isn't usually meaningful. For symbolic links this specifies the length of the file name the link refers to.
This is the last access time for the file. the section called “File Times”.
This is the fractional part of the last access time for the file. the section called “File Times”.
This is the time of the last modification to the contents of the file. the section called “File Times”.
This is the fractional part of the time of the last modification to the contents of the file. the section called “File Times”.
This is the time of the last modification to the attributes of the file. the section called “File Times”.
This is the fractional part of the time of the last modification to the attributes of the file. the section called “File Times”.
This is the amount of disk space that the file occupies, measured in units of 512-byte blocks.
The optimal block size for reading of writing this file, in bytes. You might use this size for allocating the buffer space for reading of writing the file. (This is unrelated to st_blocks.)
Some of the file attributes have special data type names which exist specifically for those attributes. (They are all aliases for well-known integer types that you know and love.) These typedef names are defined in the header file sys/types.h as well as in sys/stat.h. Here is a list of them.
function>mode_t/function> This is an integer data type used to represent file modes. In the GNU system, this is equivalent to unsigned int.
function>ino_t/function> This is an arithmetic data type used to represent file serial numbers. (In Unix jargon, these are sometimes called inode numbers.) In the GNU system, this type is equivalent to unsigned long int.
If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by ino64_t.
function>ino64_t/function> This is an arithmetic data type used to represent file serial numbers for the use in LFS. In the GNU system, this type is equivalent to unsigned long longint.
When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name ino_t.
function>dev_t/function> This is an arithmetic data type used to represent file device numbers. In the GNU system, this is equivalent to int.
function>nlink_t/function> This is an arithmetic data type used to represent file link counts. In the GNU system, this is equivalent to unsigned short int.
function>blkcnt_t/function> This is an arithmetic data type used to represent block counts. In the GNU system, this is equivalent to unsigned long int.
If the source is compiled with _FILE_OFFSET_BITS == 64 this type is transparently replaced by blkcnt64_t.
function>blkcnt64_t/function> This is an arithmetic data type used to represent block counts for the use in LFS. In the GNU system, this is equivalent to unsigned long long int.
When compiling with _FILE_OFFSET_BITS == 64 this type is available under the name blkcnt_t.
To examine the attributes of files, use the functions stat, fstat and lstat. They return the attribute information in a struct stat object. All three functions are declared in the header file sys/stat.h.
int function>stat/function> (const char *filename, struct stat *buf) The stat function returns information about the attributes of the file named by filename in the structure pointed to by buf.
If filename is the name of a symbolic link, the attributes you get describe the file that the link points to. If the link points to a nonexistent file name, then stat fails reporting a nonexistent file.
The return value is 0 if the operation is successful, or -1 on failure. In addition to the usual file name errors (the section called “File Name Errors”, the following errno error conditions are defined for this function:
The file named by filename doesn't exist.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact stat64 since the LFS interface transparently replaces the normal implementation.
int function>stat64/function> (const char *filename, struct stat64 *buf) This function is similar to stat but it is also able to work on files larger then 2^31 bytes on 32-bit systems. To be able to do this the result is stored in a variable of type struct stat64 to which buf must point.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name stat and so transparently replaces the interface for small files on 32-bit machines.
int function>fstat/function> (int filedes, struct stat *buf) The fstat function is like stat, except that it takes an open file descriptor as an argument instead of a file name. Chapter 14.
Like stat, fstat returns 0 on success and -1 on failure. The following errno error conditions are defined for fstat:
The filedes argument is not a valid file descriptor.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact fstat64 since the LFS interface transparently replaces the normal implementation.
int function>fstat64/function> (int filedes, struct stat64 *buf) This function is similar to fstat but is able to work on large files on 32-bit platforms. For large files the file descriptor filedes should be obtained by open64 or creat64. The buf pointer points to a variable of type struct stat64 which is able to represent the larger values.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name fstat and so transparently replaces the interface for small files on 32-bit machines.
int function>lstat/function> (const char *filename, struct stat *buf) The lstat function is like stat, except that it does not follow symbolic links. If filename is the name of a symbolic link, lstat returns information about the link itself; otherwise lstat works like stat. the section called “Symbolic Links”.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is in fact lstat64 since the LFS interface transparently replaces the normal implementation.
int function>lstat64/function> (const char *filename, struct stat64 *buf) This function is similar to lstat but it is also able to work on files larger then 2^31 bytes on 32-bit systems. To be able to do this the result is stored in a variable of type struct stat64 to which buf must point.
When the sources are compiled with _FILE_OFFSET_BITS == 64 this function is available under the name lstat and so transparently replaces the interface for small files on 32-bit machines.
The file mode, stored in the st_mode field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the type code, which you can use to tell whether the file is a directory, socket, symbolic link, and so on. For details about access permissions see the section called “The Mode Bits for Access Permission”.
There are two ways you can access the file type information in a file mode. Firstly, for each file type there is a predicate macro which examines a given file mode and returns whether it is of that type or not. Secondly, you can mask out the rest of the file mode to leave just the file type code, and compare this against constants for each of the supported file types.
All of the symbols listed in this section are defined in the header file sys/stat.h. The following predicate macros test the type of a file, given the value m which is the st_mode field returned by stat on that file:
int function>S_ISDIR/function> (mode_t m) This macro returns non-zero if the file is a directory.
int function>S_ISCHR/function> (mode_t m) This macro returns non-zero if the file is a character special file (a device like a terminal).
int function>S_ISBLK/function> (mode_t m) This macro returns non-zero if the file is a block special file (a device like a disk).
int function>S_ISREG/function> (mode_t m) This macro returns non-zero if the file is a regular file.
int function>S_ISFIFO/function> (mode_t m) This macro returns non-zero if the file is a FIFO special file, or a pipe. Chapter 16.
int function>S_ISLNK/function> (mode_t m) This macro returns non-zero if the file is a symbolic link. the section called “Symbolic Links”.
int function>S_ISSOCK/function> (mode_t m) This macro returns non-zero if the file is a socket. Chapter 17.
An alternate non-POSIX method of testing the file type is supported for compatibility with BSD. The mode can be bitwise AND-ed with S_IFMT to extract the file type code, and compared to the appropriate constant. For example,
S_ISCHR (mode)
is equivalent to:
((mode S_IFMT) == S_IFCHR)
int function>S_IFMT/function> This is a bit mask used to extract the file type code from a mode value.
These are the symbolic names for the different file type codes:
The POSIX.1b standard introduced a few more objects which possibly can be implemented as object in the filesystem. These are message queues, semaphores, and shared memory objects. To allow differentiating these objects from other files the POSIX standard introduces three new test macros. But unlike the other macros it does not take the value of the st_mode field as the parameter. Instead they expect a pointer to the whole struct stat structure.
int function>S_TYPEISMQ/function> (struct stat *s) If the system implement POSIX message queues as distinct objects and the file is a message queue object, this macro returns a non-zero value. In all other cases the result is zero.
int function>S_TYPEISSEM/function> (struct stat *s) If the system implement POSIX semaphores as distinct objects and the file is a semaphore object, this macro returns a non-zero value. In all other cases the result is zero.
int function>S_TYPEISSHM/function> (struct stat *s) If the system implement POSIX shared memory objects as distinct objects and the file is an shared memory object, this macro returns a non-zero value. In all other cases the result is zero.
Every file has an owner which is one of the registered user names defined on the system. Each file also has a group which is one of the defined groups. The file owner can often be useful for showing you who edited the file (especially when you edit with GNU Emacs), but its main purpose is for access control.
The file owner and group play a role in determining access because the file has one set of access permission bits for the owner, another set that applies to users who belong to the file's group, and a third set of bits that applies to everyone else. the section called “How Your Access to a File is Decided”, for the details of how access is decided based on this data.
When a file is created, its owner is set to the effective user ID of the process that creates it (the section called “The Persona of a Process”). The file's group ID may be set to either the effective group ID of the process, or the group ID of the directory that contains the file, depending on the system where the file is stored. When you access a remote file system, it behaves according to its own rules, not according to the system your program is running on. Thus, your program must be prepared to encounter either kind of behavior no matter what kind of system you run it on.
You can change the owner and/or group owner of an existing file using the chown function. This is the primitive for the chown and chgrp shell commands.
The prototype for this function is declared in unistd.h.
int function>chown/function> (const char *filename, uid_t owner, gid_t group) The chown function changes the owner of the file filename to owner, and its group owner to group.
Changing the owner of the file on certain systems clears the set-user-ID and set-group-ID permission bits. (This is because those bits may not be appropriate for the new owner.) Other file permission bits are not changed.
The return value is 0 on success and -1 on failure. In addition to the usual file name errors (the section called “File Name Errors”), the following errno error conditions are defined for this function:
This process lacks permission to make the requested change.
Only privileged users or the file's owner can change the file's group. On most file systems, only privileged users can change the file owner; some file systems allow you to change the owner if you are currently the owner. When you access a remote file system, the behavior you encounter is determined by the system that actually holds the file, not by the system your program is running on.
the section called “Optional Features in File Support”, for information about the _POSIX_CHOWN_RESTRICTED macro.
The file is on a read-only file system.
int function>fchown/function> (int filedes, int owner, int group) This is like chown, except that it changes the owner of the open file with descriptor filedes.
The return value from fchown is 0 on success and -1 on failure. The following errno error codes are defined for this function:
The filedes argument is not a valid file descriptor.
The filedes argument corresponds to a pipe or socket, not an ordinary file.
This process lacks permission to make the requested change. For details see chmod above.
The file resides on a read-only file system.
The file mode, stored in the st_mode field of the file attributes, contains two kinds of information: the file type code, and the access permission bits. This section discusses only the access permission bits, which control who can read or write the file. the section called “Testing the Type of a File”, for information about the file type code.
All of the symbols listed in this section are defined in the header file sys/stat.h. These symbolic constants are defined for the file mode bits that control access permission for the file:
Read permission bit for the owner of the file. On many systems this bit is 0400. S_IREAD is an obsolete synonym provided for BSD compatibility.
Write permission bit for the owner of the file. Usually 0200. S_IWRITE is an obsolete synonym provided for BSD compatibility.
Execute (for ordinary files) or search (for directories) permission bit for the owner of the file. Usually 0100. S_IEXEC is an obsolete synonym provided for BSD compatibility.
Read permission bit for the group owner of the file. Usually 040.
Write permission bit for the group owner of the file. Usually 020.
Execute or search permission bit for the group owner of the file. Usually 010.
Execute or search permission bit for other users. Usually 01.
This is the set-user-ID on execute bit, usually 04000. the section called “How an Application Can Change Persona”.
This is the set-group-ID on execute bit, usually 02000. the section called “How an Application Can Change Persona”.
This is the sticky bit, usually 01000.
For a directory it gives permission to delete a file in that directory only if you own that file. Ordinarily, a user can either delete all the files in a directory or cannot delete any of them (based on whether the user has write permission for the directory). The same restriction applies--you must have both write permission for the directory and own the file you want to delete. The one exception is that the owner of the directory can delete any file in the directory, no matter who owns it (provided the owner has given himself write permission for the directory). This is commonly used for the /tmp directory, where anyone may create files but not delete files created by other users.
Originally the sticky bit on an executable file modified the swapping policies of the system. Normally, when a program terminated, its pages in core were immediately freed and reused. If the sticky bit was set on the executable file, the system kept the pages in core for a while as if the program were still running. This was advantageous for a program likely to be run many times in succession. This usage is obsolete in modern systems. When a program terminates, its pages always remain in core as long as there is no shortage of memory in the system. When the program is next run, its pages will still be in core if no shortage arose since the last run.
On some modern systems where the sticky bit has no useful meaning for an executable file, you cannot set the bit at all for a non-directory. If you try, chmod fails with EFTYPE; the section called “Assigning File Permissions”.
Some systems (particularly SunOS) have yet another use for the sticky bit. If the sticky bit is set on a file that is not executable, it means the opposite: never cache the pages of this file at all. The main use of this is for the files on an NFS server machine which are used as the swap area of diskless client machines. The idea is that the pages of the file will be cached in the client's memory, so it is a waste of the server's memory to cache them a second time. With this usage the sticky bit also implies that the filesystem may fail to record the file's modification time onto disk reliably (the idea being that no-one cares for a swap file).
This bit is only available on BSD systems (and those derived from them). Therefore one has to use the _BSD_SOURCE feature select macro to get the definition (the section called “Feature Test Macros”).
The actual bit values of the symbols are listed in the table above so you can decode file mode values when debugging your programs. These bit values are correct for most systems, but they are not guaranteed.
Warning: Writing explicit numbers for file permissions is bad practice. Not only is it not portable, it also requires everyone who reads your program to remember what the bits mean. To make your program clean use the symbolic names.
Recall that the operating system normally decides access permission for a file based on the effective user and group IDs of the process and its supplementary group IDs, together with the file's owner, group and permission bits. These concepts are discussed in detail in the section called “The Persona of a Process”.
If the effective user ID of the process matches the owner user ID of the file, then permissions for read, write, and execute/search are controlled by the corresponding "user" (or "owner") bits. Likewise, if any of the effective group ID or supplementary group IDs of the process matches the group owner ID of the file, then permissions are controlled by the "group" bits. Otherwise, permissions are controlled by the "other" bits.
Privileged users, like root, can access any file regardless of its permission bits. As a special case, for a file to be executable even by a privileged user, at least one of its execute bits must be set.
The primitive functions for creating files (for example, open or mkdir) take a mode argument, which specifies the file permissions to give the newly created file. This mode is modified by the process's file creation mask, or umask, before it is used.
The bits that are set in the file creation mask identify permissions that are always to be disabled for newly created files. For example, if you set all the "other" access bits in the mask, then newly created files are not accessible at all to processes in the "other" category, even if the mode argument passed to the create function would permit such access. In other words, the file creation mask is the complement of the ordinary access permissions you want to grant.
Programs that create files typically specify a mode argument that includes all the permissions that make sense for the particular file. For an ordinary file, this is typically read and write permission for all classes of users. These permissions are then restricted as specified by the individual user's own file creation mask.
To change the permission of an existing file given its name, call chmod. This function uses the specified permission bits and ignores the file creation mask.
In normal use, the file creation mask is initialized by the user's login shell (using the umask shell command), and inherited by all subprocesses. Application programs normally don't need to worry about the file creation mask. It will automatically do what it is supposed to do.
When your program needs to create a file and bypass the umask for its access permissions, the easiest way to do this is to use fchmod after opening the file, rather than changing the umask. In fact, changing the umask is usually done only by shells. They use the umask function.
The functions in this section are declared in sys/stat.h. mode_t function>umask/function> (mode_t mask) The umask function sets the file creation mask of the current process to mask, and returns the previous value of the file creation mask.
Here is an example showing how to read the mask with umask without changing it permanently:
mode_t read_umask (void) { mode_t mask = umask (0); umask (mask); return mask; }
However, it is better to use getumask if you just want to read the mask value, because it is reentrant (at least if you use the GNU operating system).
mode_t function>getumask/function> (void) Return the current value of the file creation mask for the current process. This function is a GNU extension.
int function>chmod/function> (const char *filename, mode_t mode) The chmod function sets the access permission bits for the file named by filename to mode.
If filename is a symbolic link, chmod changes the permissions of the file pointed to by the link, not those of the link itself.
This function returns 0 if successful and -1 if not. In addition to the usual file name errors (the section called “File Name Errors”), the following errno error conditions are defined for this function:
The named file doesn't exist.
This process does not have permission to change the access permissions of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.
The file resides on a read-only file system.
mode has the S_ISVTX bit (the "sticky bit") set, and the named file is not a directory. Some systems do not allow setting the sticky bit on non-directory files, and some do (and only some of those assign a useful meaning to the bit for non-directory files).
You only get EFTYPE on systems where the sticky bit has no useful meaning for non-directory files, so it is always safe to just clear the bit in mode and call chmod again. the section called “The Mode Bits for Access Permission”, for full details on the sticky bit.
int function>fchmod/function> (int filedes, int mode) This is like chmod, except that it changes the permissions of the currently open file given by filedes.
The return value from fchmod is 0 on success and -1 on failure. The following errno error codes are defined for this function:
The filedes argument is not a valid file descriptor.
The filedes argument corresponds to a pipe or socket, or something else that doesn't really have access permissions.
This process does not have permission to change the access permissions of this file. Only the file's owner (as judged by the effective user ID of the process) or a privileged user can change them.
The file resides on a read-only file system.
In some situations it is desirable to allow programs to access files or devices even if this is not possible with the permissions granted to the user. One possible solution is to set the setuid-bit of the program file. If such a program is started the effective user ID of the process is changed to that of the owner of the program file. So to allow write access to files like /etc/passwd, which normally can be written only by the super-user, the modifying program will have to be owned by root and the setuid-bit must be set.
But beside the files the program is intended to change the user should not be allowed to access any file to which s/he would not have access anyway. The program therefore must explicitly check whether the user would have the necessary access to a file, before it reads or writes the file.
To do this, use the function access, which checks for access permission based on the process's real user ID rather than the effective user ID. (The setuid feature does not alter the real user ID, so it reflects the user who actually ran the program.)
There is another way you could check this access, which is easy to describe, but very hard to use. This is to examine the file mode bits and mimic the system's own access computation. This method is undesirable because many systems have additional access control features; your program cannot portably mimic them, and you would not want to try to keep track of the diverse features that different systems have. Using access is simple and automatically does whatever is appropriate for the system you are using.
access is only only appropriate to use in setuid programs. A non-setuid program will always use the effective ID rather than the real ID.
The symbols in this section are declared in unistd.h.
int function>access/function> (const char *filename, int how) The access function checks to see whether the file named by filename can be accessed in the way specified by the how argument. The how argument either can be the bitwise OR of the flags R_OK, W_OK, X_OK, or the existence test F_OK.
This function uses the real user and group IDs of the calling process, rather than the effective IDs, to check for access permission. As a result, if you use the function from a setuid or setgid program (the section called “How an Application Can Change Persona”), it gives information relative to the user who actually ran the program.
The return value is 0 if the access is permitted, and -1 otherwise. (In other words, treated as a predicate function, access returns true if the requested access is denied.)
In addition to the usual file name errors (the section called “File Name Errors”), the following errno error conditions are defined for this function:
The access specified by how is denied.
The file doesn't exist.
Write permission was requested for a file on a read-only file system.
These macros are defined in the header file unistd.h for use as the how argument to the access function. The values are integer constants. int function>R_OK/function> Flag meaning test for read permission.
int function>W_OK/function> Flag meaning test for write permission.
int function>X_OK/function> Flag meaning test for execute/search permission.
int function>F_OK/function> Flag meaning test for existence of the file.
Each file has three time stamps associated with it: its access time, its modification time, and its attribute modification time. These correspond to the st_atime, st_mtime, and st_ctime members of the stat structure; see the section called “File Attributes”.
All of these times are represented in calendar time format, as time_t objects. This data type is defined in time.h. For more information about representation and manipulation of time values, see the section called “Calendar Time”. Reading from a file updates its access time attribute, and writing updates its modification time. When a file is created, all three time stamps for that file are set to the current time. In addition, the attribute change time and modification time fields of the directory that contains the new entry are updated.
Adding a new name for a file with the link function updates the attribute change time field of the file being linked, and both the attribute change time and modification time fields of the directory containing the new name. These same fields are affected if a file name is deleted with unlink, remove or rmdir. Renaming a file with rename affects only the attribute change time and modification time fields of the two parent directories involved, and not the times for the file being renamed.
Changing the attributes of a file (for example, with chmod) updates its attribute change time field.
You can also change some of the time stamps of a file explicitly using the utime function--all except the attribute change time. You need to include the header file utime.h to use this facility. function>struct utimbuf/function> The utimbuf structure is used with the utime function to specify new access and modification times for a file. It contains the following members:
This is the access time for the file.
This is the modification time for the file.
int function>utime/function> (const char *filename, const struct utimbuf *times) This function is used to modify the file times associated with the file named filename.
If times is a null pointer, then the access and modification times of the file are set to the current time. Otherwise, they are set to the values from the actime and modtime members (respectively) of the utimbuf structure pointed to by times.
The attribute modification time for the file is set to the current time in either case (since changing the time stamps is itself a modification of the file attributes).
The utime function returns 0 if successful and -1 on failure. In addition to the usual file name errors (the section called “File Name Errors”), the following errno error conditions are defined for this function:
There is a permission problem in the case where a null pointer was passed as the times argument. In order to update the time stamp on the file, you must either be the owner of the file, have write permission for the file, or be a privileged user.
The file doesn't exist.
If the times argument is not a null pointer, you must either be the owner of the file or be a privileged user.
The file lives on a read-only file system.
Each of the three time stamps has a corresponding microsecond part, which extends its resolution. These fields are called st_atime_usec, st_mtime_usec, and st_ctime_usec; each has a value between 0 and 999,999, which indicates the time in microseconds. They correspond to the tv_usec field of a timeval structure; see the section called “High-Resolution Calendar”.
The utimes function is like utime, but also lets you specify the fractional part of the file times. The prototype for this function is in the header file sys/time.h. int function>utimes/function> (const char *filename, struct timeval tvp[2]) This function sets the file access and modification times of the file filename. The new file access time is specified by tvp[0], and the new modification time by tvp[1]. This function comes from BSD.
The return values and error conditions are the same as for the utime function.
Normally file sizes are maintained automatically. A file begins with a size of 0 and is automatically extended when data is written past its end. It is also possible to empty a file completely by an open or fopen call.
However, sometimes it is necessary to reduce the size of a file. This can be done with the truncate and ftruncate functions. They were introduced in BSD Unix. ftruncate was later added to POSIX.1.
Some systems allow you to extend a file (creating holes) with these functions. This is useful when using memory-mapped I/O (the section called “Memory-mapped I/O”), where files are not automatically extended. However, it is not portable but must be implemented if mmap allows mapping of files (i.e., _POSIX_MAPPED_FILES is defined).
Using these functions on anything other than a regular file gives undefined results. On many systems, such a call will appear to succeed, without actually accomplishing anything.
int function>truncate/function> (const char *filename, off_t length) The truncate function changes the size of filename to length. If length is shorter than the previous length, data at the end will be lost. The file must be writable by the user to perform this operation.
If length is longer, holes will be added to the end. However, some systems do not support this feature and will leave the file unchanged.
When the source file is compiled with _FILE_OFFSET_BITS == 64 the truncate function is in fact truncate64 and the type off_t has 64 bits which makes it possible to handle files up to 2^63 bytes in length.
The return value is 0 for success, or -1 for an error. In addition to the usual file name errors, the following errors may occur:
The file is a directory or not writable.
length is negative.
The operation would extend the file beyond the limits of the operating system.
A hardware I/O error occurred.
The file is "append-only" or "immutable".
The operation was interrupted by a signal.
int function>truncate64/function> (const char *name, off64_t length) This function is similar to the truncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines, which allows the handling of files with sizes up to 2^63 bytes.
When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name truncate and so transparently replaces the 32 bits interface.
int function>ftruncate/function> (int fd, off_t length) This is like truncate, but it works on a file descriptor fd for an opened file instead of a file name to identify the object. The file must be opened for writing to successfully carry out the operation.
The POSIX standard leaves it implementation defined what happens if the specified new length of the file is bigger than the original size. The ftruncate function might simply leave the file alone and do nothing or it can increase the size to the desired size. In this later case the extended area should be zero-filled. So using ftruncate is no reliable way to increase the file size but if it is possible it is probably the fastest way. The function also operates on POSIX shared memory segments if these are implemented by the system.
ftruncate is especially useful in combination with mmap. Since the mapped region must have a fixed size one cannot enlarge the file by writing something beyond the last mapped page. Instead one has to enlarge the file itself and then remap the file with the new size. The example below shows how this works.
When the source file is compiled with _FILE_OFFSET_BITS == 64 the ftruncate function is in fact ftruncate64 and the type off_t has 64 bits which makes it possible to handle files up to 2^63 bytes in length.
The return value is 0 for success, or -1 for an error. The following errors may occur:
fd does not correspond to an open file.
fd is a directory or not open for writing.
length is negative.
The operation would extend the file beyond the limits of the operating system.
A hardware I/O error occurred.
The file is "append-only" or "immutable".
The operation was interrupted by a signal.
int function>ftruncate64/function> (int id, off64_t length) This function is similar to the ftruncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines which allows the handling of files with sizes up to 2^63 bytes.
When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name ftruncate and so transparently replaces the 32 bits interface.
As announced here is a little example of how to use ftruncate in combination with mmap:
int fd; void *start; size_t len; int add (off_t at, void *block, size_t size) { if (at + size len) { /* Resize the file and remap. */ size_t ps = sysconf (_SC_PAGESIZE); size_t ns = (at + size + ps - 1) ~(ps - 1); void *np; if (ftruncate (fd, ns) 0) return -1; np = mmap (NULL, ns, PROT_READ|PROT_WRITE, MAP_SHARED, fd, 0); if (np == MAP_FAILED) return -1; start = np; len = ns; } memcpy ((char *) start + at, block, size); return 0; }
The function add writes a block of memory at an arbitrary position in the file. If the current size of the file is too small it is extended. Note the it is extended by a round number of pages. This is a requirement of mmap. The program has to keep track of the real size, and when it has finished a final ftruncate call should set the real size of the file.