unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



chfile(8)							    chfile(8)



NAME

  chfile - Changes attributes of AdvFS files

SYNOPSIS

  /usr/sbin/chfile [-l on | off] [-L on	| off] filename...

OPTIONS

  -l on	| off
      Enables or disables (on |	off) forced synchronous	write requests to the
      specified	filename. By default, forced synchronous write requests	to a
      file are off.

  -L on	| off
      Enables or disables (on |	off) persistent	atomic-write data logging on
      the specified filename. By default, atomic-write data logging is off.

OPERAND

  filename...
      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:

  Asynchronous I/O
      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.

  Forced synchronous I/O
      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.

  Persistent atomic-write data logging I/O
      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 generally	not guaranteed to be
      the case in POSIX-compliant file systems when files are opened in	asyn-
      chronous 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 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 persistent 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	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 informa-
  tion.

  Enabling persistent atomic-write data	logging	for a file will	retard per-
  formance 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 sys-
  tem performance. See AdvFS Administration for	more information.

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 persistent 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 per-
  sistent 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 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

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

   2.  You can display similar information with	the showfile command:
	    # showfile data_logging_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

   3.  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.\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)