Use any I/O class that takes an os_ioctl_t parameter to control I/O characteristics at runtime. The control values for the I/O device can be specified in several different ways.

To use the POSIX interface, you must construct the appropriate I/O control value by a bitwise-OR of one or more flags. The actual number of POSIX flags available can vary, depending on the operating system.

The following table lists some of the POSIX values available on most platforms.


POSIX Flag	Definition
`O_APPEND`	Appends all writes to the end of the file.
`O_NONBLOCK`	Specifies that all read/write operations should return immediately if they cannot succeed. By default, operations normally block until they can be completed.
`O_RDONLY`	Only read operations are permitted with the device.
`O_RDWR`	Both read and write operations are permitted with the device.
`O_WRONLY`	Only write operations are permitted with the device.

Although POSIX flags are often used in legacy applications, the definitions of these flags are not always understood. The os_io_control class provides a set of predefined constants that can be used in place of the POSIX flags. These constants are portable across all platforms.

The following table lists all I/O control constants predefined by the os_io_control class, along with the POSIX equivalents.


Constant	Definition	POSIX Equivalent
`read_only_access`	Allows only read operations on this device. Any write operation results in an error.	`O_RDONLY`
`write_only_access`	Allows only write operations on this device. Any read operation results in an error.	`O_WRONLY`
`read_write_access`	Allows both read and write operations on this device.	`O_RDWR`
`write_append_access`	Allows write operations only and positions each write at the end of the file.	`O_WRONLY\|O_APPEND`
`read_write_append_access`	Allows read and write operations and positions each write at the end of the file.	`O_RDWR\|O_APPEND`

Another approach to specifying a control value for an I/O device applies to situations that require I/O control values to be determined at runtime. In this technique, an os_io_control object is instantiated, and its method interface is used to construct the I/O control value dynamically.

The following example shows how to use both the os_io_control object and POSIX flags with the os_file class.

Example <ospace/io/examples/ioctrl1.cpp>


  #include <iostream>
#include <ospace/file.h>

void
main()
  {
  os_file_toolkit initialize;

  // Use POSIX flags to open a file for write-only
  os_file file1
    (
    "ioctrl1.txt",
    os_open_control::create_always,
    O_WRONLY // POSIX interface
    );
  file1.write( "part 1 ", 7 );
  file1.close();

  // Use the constant interface to open a file for read-only.
  os_file file2
    (
    "ioctrl1.txt",
    os_open_control::open_existing,
    os_io_control::read_only_access
    );
  char buffer[ 100 ];
  int bytes = file2.read( buffer, sizeof( buffer ) );
  cout << "Read " << bytes << " bytes: " << buffer << endl;
  file2.close();

  // Use the os_io_control class to open a file for read/write.
  os_io_control io_control;
  io_control.set_read_write();
  io_control.append( true );

  os_file file3
    (
    "ioctrl1.txt",
    os_open_control::open_existing,
    io_control
    );
  file3.write( "part 2\n", 8 );
  file3.rewind();
  bytes = file3.read( buffer, sizeof( buffer ) );
  cout << "Read " << bytes << " bytes: " << buffer << endl;
  file3.close();
  }

Read 7 bytes: part 1
Read 15 bytes: part 1 part 2

Once an I/O object is constructed, you can change its I/O control settings using the object's method io_control() . Note that the O_RDONLY , O_WRONLY , and O_RDWR flags are only recognized when an I/O object is constructed.