chfile(8)chfile(8)NAMEchfile - Changes attributes of AdvFS files
SYNOPSIS
/usr/sbin/chfile [-l on | off] [-L on | off] filename...
OPTIONS
Enables or disables (on | off) forced synchronous write requests to the
specified filename. By default, forced synchronous write requests to a
file are off. Enables or disables (on | off) persistent atomic-write
data logging on the specified filename. By default, atomic-write data
logging is off.
OPERAND
One or more file names.
DESCRIPTION
The chfile command lets you view or change the I/O mode that will be
used when write requests are made to the file. There are three settings
for this I/O mode: The default setting. Write requests are cached, the
write system call returns to the calling program, and later (asyn‐
chronously), the data is written to the disk. When this mode is
enabled, write requests to a file behave as if the O_SYNC option had
been set when the file was opened. The write system call returns a suc‐
cess value only after the data has been successfully written to disk.
When this mode is enabled, write requests to a file are asynchronous
and written to the AdvFS log file. Should a system crash during or
after a write system call, only complete write requests (up to 8192
bytes; see restrictions below) will be processed. This atomic operation
guarantees that all (or none) of a write buffer will be in the file.
For example, if a write of an 8192-byte buffer was started and, during
the write system call or shortly thereafter, the system crashed, when
the system was rebooted, either the entire 8192 bytes of data or none
of it would have been written to the file. There would be no chance
that some (but not all) bytes of the write request would be in the
file.
When persistent atomic-write data logging is enabled on a file,
writes to the file are guaranteed to be flushed to disk in the
order that they are written by the application. This is gener‐
ally not guaranteed to be the case in POSIX-compliant file sys‐
tems when files are opened in asynchronous mode. For example,
the following code does three writes to a file: open(file);
write(buffer A); write(buffer B); write(buffer C); close(file);
If the file being written to did not use persistent atomic-write
data logging, and if the file were opened for asynchronous
writes, then it is possible that buffer C would be written to
disk before buffer B, that buffer B would be written to disk
before buffer A, and so on. This might lead to confusing file
contents if the system were to crash while the application was
running.
But if persistent atomic-write data logging is used, even if the
file is open for asynchronous writes, the buffers would be guar‐
anteed to be written to disk in the order in which the applica‐
tion wrote them.
The -l and -L options are mutually exclusive. You cannot simultane‐
ously enable both forced synchronous writes and persistent atomic-write
data logging on a file. However, you can override the current I/O
mode for a file. For example, you can change a file's I/O mode setting
from forced synchronous writes to persistent atomic-write data logging
by using the chfile-L on command.
If you do not specify the options, the command displays the current
state of the file's I/O attribute.
The chfile command can be used on AdvFS files that have been remotely
mounted across NFS. You can run the chfile command on an NFS client to
examine or change the I/O mode of AdvFS files on the NFS server.
NOTES
If you cannot enable persistent atomic-write data logging (for example,
if you have frag files or are memory mapped) you can activate temporary
on all files in a mounted fileset for the duration of the mount by
using the -o adl option of the mount command. See AdvFS Administration
for more information.
Enabling persistent atomic-write data logging for a file will retard
performance because the data is written to both the user file and the
AdvFS log file. Enabling forced synchronous writes to a file also can
retard system performance. See AdvFS Administration for more informa‐
tion.
RESTRICTIONS
To use the chfile command on AdvFS files that are mounted across NFS,
the NFS property list daemon, proplistd, must be running on the NFS
client and the fileset must have been mounted on the client using the
proplist option.
Only writes of up to 8192 bytes are guaranteed to be atomic for files
that use persistent atomic-write data logging. Writes that are greater
than 8192 bytes are written in segments that are at most 8192 bytes in
length with each segment an atomic-write. If an error should occur
(disk full, ulimit, and so on), the return value from the write will
specify how much was successfully written. When writing to an AdvFS
file that has been mounted across NFS, a further restriction applies:
the offset into the file of the write must be on an 8K page boundary
because NFS performs I/O on 8K page boundaries.
The showfile command does not display the I/O mode for files that are
mounted across NFS. To display the I/O mode of these files, use the
chfile command.
Usually AdvFS, when operating on small files that do not have a size
that is a multiple of 8K, puts the last part of the files (their frags)
into a special metadata file called the fileset frag file as a way to
reduce disk fragmentation. For example, a file that does not use per‐
sistent atomic-write data logging and has had 20K of data written to
it will occupy 20K of disk space (as displayed by the du command).
Files that use persistent atomic-write data logging are exempt from
this behavior. As a result, they always have a disk usage (as displayed
by the du command) that is a multiple of 8K. For example, a file that
has persistent atomic-write data logging enabled and has had 20K of
data written to it occupies 24K of disk space.
If a file has a frag, an attempt to activate persistent atomic-write
data logging on it will fail.
Files that use persistent atomic-write data logging cannot be memory-
mapped through the mmap system call. The error ENOTSUP is returned if
the attempt is made. If a file has been memory-mapped through the mmap
system call, an attempt to activate persistent atomic-write data log‐
ging on it fails with the same error.
EXIT STATUS
The utility returns a 0 (zero) on success and a 1 (one) on failure.
EXAMPLE
The following example queries the file I/O mode. # ls -l total 8712
drwx------ 2 root system 8192 Nov 4 06:16 .tags -rwxr-xr-x 1
root system 8435752 Nov 5 08:43 data_logging_file -rw-r--r-- 1
root system 250880 Nov 5 08:44 forced_sync_file -rw-r--r-- 1 root
system 195320 Nov 5 08:44 normal_async_file -rw-r----- 1 root
operator 8192 Nov 4 06:16 quota.group
# chfile data_logging_file I/O type = atomic write data logging #
chfile forced_sync_file I/O type = forced synchronous writes # chfile
normal_async_file I/O type = normal asynchronous writes You can display
similar information with the showfile command: # showfile data_log‐
ging_file forced_sync_file normal_async_file
Id Vol PgSz Pages XtntType Segs SegSz I/O Perf File 8.8001 1
16 1030 simple ** ** ftx 100% data_logging_file 7.8008 2
16 31 simple ** ** sync 100% forced_sync_file 6.8001 1
16 24 simple ** ** async 100% normal_async_file The follow‐
ing code fragment queries the current I/O mode for an AdvFS file:
.
.
. advfs_opT myop; int fd; int io_mode;
.
.
. myop.version = ADVFS_OP_CURR_VERSION; myop.operation =
ADVFS_AW_DATA_LOGGING; myop.action = ADVFS_GET_INFO; myop.info_buf
= &io_mode; myop.info_buf_size = sizeof(int); ret = fcntl(fd,
F_ADVFS_OP, &myop); if (ret) {
perror("fcnt1 failed"); if (io_mode == ADVFS_ASYNC_IO)
printf("I/O mode is asynchronous.\n"); else if (io_mode ==
ADVFS_DATA_LOGGING_IO)
printf("I/O mode is atomic write data logging.\n"); else if
(io_mode == ADVFS_SYNC_IO)
printf("I/O mode is forced synchronous writes.\n");
SEE ALSO
Commands: showfile(8), mount(8),
chfsets(8)
Files: advfs(4)chfile(8)