chfile(8)						      System Manager's Manual							 chfile(8)

NAME

       chfile - 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) atomic-write data logging on the specified filename. By default, atomic-write data  log-
       ging 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 set-
       tings for this I/O mode: The default setting.  Write requests are cached, the write system call returns to the calling program,	and  later
       (asynchronously),  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 success 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 AdvFS 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 generally not guaranteed to be the case in POSIX-compliant file systems 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 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  atomic-write  data logging is used, even if the file is open for asynchronous writes, the buffers would be guaranteed to be
	      written to disk in the order in which the application wrote them.

       The -l and -L options are mutually exclusive.  You cannot simultaneously enable both forced synchronous writes and atomic-write	data  log-
       ging  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 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

       Enabling  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.

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 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 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 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 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 atomic-write data logging on it will fail.

       Files that use 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 active atomic-write data logging 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
       following 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.
"); else if (io_mode == ADVFS_DATA_LOGGING_IO)
	   printf("I/O mode is atomic write data logging.
"); else if (io_mode == ADVFS_SYNC_IO)
	   printf("I/O mode is forced synchronous writes.
");

SEE ALSO

       Commands: showfile(8)

       Files: advfs(4)

																	 chfile(8)