NAME
SETIOMODE - Sets the I/O mode of a file and performs a glo-
bal synchronization operation.
SYNOPSIS
#include <nx.h>
void setiomode(
int fildes,
int iomode );
PARAMETERS
fildes A file descriptor representing an open file.
iomode The I/O mode to be assigned to the file associated
with fildes. Values for the iomode parameter are
as follows:
M_UNIX Each node has its own file pointer;
access is unrestricted.
M_LOG All nodes use the same file pointer;
access is first come, first served;
records may be of variable length.
M_SYNC All nodes use the same file pointer;
access is in node order; records are
in node order but may be of variable
length.
M_RECORD Each node has its own file pointer;
access is first come, first served;
records are in node order and of
fixed length.
M_GLOBAL All nodes use the same file pointer,
all nodes perform the same opera-
tions.
M_ASYNC Each node has its own file pointer;
access is unrestricted; I/O atomi-
city is not preserved in order to
allow multiple readers/multiple
writers and records of variable
length.
Refer to the ``Description'' section for detailed
information on each mode.
DESCRIPTION
The setiomode() function changes the I/O mode of an open
shared file. A shared file is a file that is opened for
access by all nodes in an application. To explicitly specify
an I/O mode at the time a file is opened, use the gopen()
function.
The default I/O mode shared files are opened with depends on
two things: the type of file and the value of the
PFS_ASYNC_DFLT bootmagic string. Behavior is as follows:
non-PFS files
The default I/O mode is M_UNIX for all non-PFS
files. This behavior holds true regardless of
the PFS_ASYNC_DFLT bootmagic string.
PFS files The default I/O mode is M_UNIX when
PFS_ASYNC_DFLT is set to any value other than 1.
When PFS_ASYNC_DFLT is set to 1, the default I/O
mode is M_ASYNC.
This method of determining the default I/O mode also holds
true during fork() operations. In other words, the I/O modes
associated with the parent process' file descriptors are not
inherited by the child process. Instead, all I/O modes in
the child process default accordingly. When using the dup()
function to duplicate a file, the file descriptor for the
duplicate file is reset to the I/O mode M_UNIX.
NOTE
To determine the current setting for PFS_ASYNC_DFLT,
use the getmagic command. For information on this com-
mand, see the getmagic manual page.
Each node calling setiomode() must specify a file descriptor
with the fildes parameter that refers to the same file. The
file pointer must be in the same position in the file for
each node at the time the call to setiomode() is made.
In addition to setting the file's I/O mode, setiomode() per-
forms a global synchronizing operation like that of the
gsync() call. All nodes must call the setiomode() function
before any node can continue executing. In the M_LOG,
M_SYNC, M_RECORD, and M_GLOBAL I/O modes, closing the file
also performs a global synchronizing operation.
Use the iomode() function to return a file's current I/O
mode.
M_UNIX (MODE 0)
The features of this mode are as follows:
o Each node has a unique file pointer.
o Nodes are not synchronized.
o Variable-length, unordered records.
This mode conforms with standard UNIX file sharing semantics
for different processes accessing the same file. In this
mode, each node maintains its own file pointer and can
access information anywhere in the file at any time. If two
nodes write to the same place in the file, the latest data
written by one node overwrites the data written previously
by the other node.
This mode is often used when each node is responsible for
data in a specific area of a file.
Although nodes are not synchronized as in the M_SYNC mode,
this mode currently supports only a single reader/single
writer. If multiple readers/multiple writers are required,
use the M_RECORD or M_ASYNC modes. If all nodes read the
same data, use the M_GLOBAL mode.
Depending on the shared file type (PFS or non-PFS) and the
PFS_ASYNC_DFLT bootmagic variable setting, M_UNIX can be the
default I/O mode (see the ``Description'' section for more
information).
M_LOG (MODE 1)
The features of this mode are as follows:
o Shared file pointer.
o Nodes are not synchronized.
o Variable-length, unordered records.
In this mode, all nodes use the same file pointer. I/O
requests from nodes are handled on a first-come,
first-served basis. Because requests can be performed in any
order, the order of the data in the file may vary from run
to run.
This mode is often used for log files. The files stdin,
stdout, and stderr are always opened in this mode.
Because only one node may access the file at a time, this
mode has lower performance than the M_RECORD, M_GLOBAL, and
M_ASYNC modes.
M_SYNC (MODE 2)
The features of this mode are as follows:
o Shared file pointer.
o Nodes are synchronized.
o Variable-length records, stored in node order.
In this mode, all nodes use the same file pointer, but I/O
requests are handled in node order. This mode treats file
accesses as global operations in which all nodes must com-
plete their access before any node can access the file
again. The amount of data requested by the application to be
read or written may vary from node to node.
In this mode, all nodes must perform the same file opera-
tions in the same order. The only valid use of the lseek()
and eseek() function is for all nodes to seek to the same
position in the file prior to an access.
Because nodes must access the file in node order, this mode
has the lowest performance than the M_RECORD, M_GLOBAL, and
M_ASYNC modes.
M_RECORD (MODE 3)
The features of this mode are as follows:
o Unique file pointer.
o Nodes are not synchronized.
o Fixed-length records, stored in node order.
o Highly parallel.
In this mode, each node maintains its own file pointer and
the application can access the file at any time. The data
for each corresponding access (that is, the nth read or
write) must be the same length for all nodes. This guaran-
tees that each node reads/writes to separate areas of the
file, allowing the file system to provide access to the file
in a highly parallel fashion.
NOTE
No verification is performed. You must make sure that
all the nodes in the application make the same calls
and read and write the same number of bytes.
Files created in this mode resemble files created in the
M_SYNC mode (that is, the data appear in node order). The
application should perform the same file operations in the
same order on all nodes. However, for higher performance
only the lseek() and eseek() system calls are synchronized.
The only valid use of one of these calls is for all nodes to
seek to the same position in the file prior to an access.
Because all nodes may access the file in parallel when
either reading or writing, this mode offers higher perfor-
mance than the M_UNIX, M_LOG, and M_SYNC modes.
M_GLOBAL (MODE 4)
The features of this mode are as follows:
o Shared file pointer.
o Nodes are synchronized.
o Variable-length, unordered records.
o All nodes access the same data.
o Data read/written from/to disk only once.
This mode coordinates I/O requests so that multiple identi-
cal I/O requests to the same file from different nodes are
not issued.
In the M_GLOBAL mode, all nodes use the same file pointer
for a file, and each I/O request from an application is a
global operation in which all nodes must perform the same
file accesses in the same order. All nodes read the same
data and all nodes write the same data, although the data
written is not checked. All write operations return the same
number of bytes written. The only valid use for the lseek()
or eseek() functions is for all nodes to seek to the same
position in the file prior to an access.
Because identical requests are combined into a single
request, the M_GLOBAL mode provides a higher-performance
alternative to the M_UNIX mode when all nodes read and write
the same data. For example, this mode is useful for parallel
applications that initialize by having all nodes sequen-
tially read the same data file.
M_ASYNC (MODE 5)
The features of this mode are as follows:
o Each node has a unique file pointer.
o Nodes are not synchronized.
o Variable-length, unordered records.
o Multiple readers/multiple writers are allowed with no res-
trictions.
The M_ASYNC mode is similar to the M_UNIX mode, except it
does not support standard UNIX file sharing semantics for
different processes accessing the same file. This mode does
not guarantee that I/O operations are atomic. For example,
if multiple nodes write to the same area of a file at the
same time, parts of the file area may contain data from one
write while other parts may contain data from other writes.
If a node reads from the same area of the file at this time,
the returned data may consist partially of old data and par-
tially of new data. Other I/O modes guarantee that I/O
operations are atomic, so that only the data from one write
is seen in areas of the file where multiple processes are
writing simultaneously, and all nodes are notified when the
file size changes.
In this mode, an application must control parallel access to
the file. This allows multiple readers and/or multiple writ-
ers to access the file simultaneously with no restrictions
on record size or file offset.
If a file is opened with the O_APPEND flag and multiple
nodes write to the file simultaneously, the results are
unpredictable because nodes are not synchronized whenever
the end-of-file changes.
It is not required that all nodes read or write to the file,
and there are no restrictions on using lseek() or eseek().
Because all nodes may access the file in parallel when
either reading or writing, this mode offers higher perfor-
mance than the M_UNIX, M_LOG, and M_SYNC modes.
You can cause M_ASYNC mode to be the default I/O mode by
setting the PFS_ASYNC_DFLT bootmagic string to one (1).
RETURN VALUES
Upon successful completion, the setiomode() function returns
control to the calling process; no values are returned. Oth-
erwise, the setiomode() function writes an error message on
the standard error output and causes the calling process to
terminate.
Upon successful completion, the _setiomode() function
returns 0 (zero). Otherwise, the _setiomode() function
returns -1 and sets errno to indicate the error.
ERRORS
If the _setiomode() function fails, errno may be set to one
of the following error code values:
EBADF The fildes parameter is not a valid file descrip-
tor.
EINVAL The given value for iomode is not a valid I/O
mode.
EINVAL The file referenced by filedes is not a regular
file.
EMIXIO The given filedes is invalid because all nodes
have not specified a filedes that represents the
same file.
EMIXIO The given value for iomode is not valid because
all nodes sharing the file represented by fildes
have not used the same value.
EMIXIO In I/O modes M_LOG, M_SYNC, M_RECORD, or M_GLOBAL,
all nodes sharing the file have not set the file
pointer to the same location.
EXAMPLES
The following example shows how to use the setiomode() func-
tion to set the I/O mode after opening a file, but before
writing to the file.
#include <fcntl.h>
#include <nx.h>
long iam;
main()
{
int fd;
char buffer[80];
iam = mynode();
fd = gopen(``/tmp/mydata'',O_CREAT | O_TRUNC | O_RDWR, M_UNIX,
0644);
/* Read some data from the file and do some computation */
/* on the data before changing the file mode and writing */
/* the file. */
setiomode(fd, M_RECORD);
sprintf(buffer,''Hello from node %d\n'',iam);
cwrite(fd, buffer, strlen(buffer));
close(fd);
}
LIMITATIONS AND WORKAROUNDS
For information about limitations and workarounds, see the
release notes files in /usr/share/release_notes.
SEE ALSO
cread(), cwrite(), gopen(), iomode(), iread(), iwrite()
OSF/1 Programmer's Reference: dup(2), fork(2), open(2)
Acknowledgement and Disclaimer