NAME
	  GOPEN	- Performs a global open of a file for reading or
	  writing, sets	the I/O	mode of	the file, and performs a glo-
	  bal synchronization.

     SYNOPSIS
	  #include <fcntl.h>
	  #include <nx.h>

	  int gopen(
	       const char *path,
	       int oflag,
	       int iomode,
	       mode_t mode );

     PARAMETERS
	  path	    Pointer to a pathname of the file to be opened or
		    created. If	the path parameter refers to a sym-
		    bolic link,	the gopen() function opens the file
		    pointed to by the symbolic link.

	  oflag	    Specifies the type of access, special open pro-
		    cessing, the type of update, and the initial state
		    of the open	file. The parameter value is con-
		    structed by	logically ORing	the special open pro-
		    cessing flags. These flags are defined in the
		    fcntl.h header file	and are	described in the OSF/1
		    open(2) manual page.

	  iomode    I/O	mode to	be assigned to the file	associated
		    with fildes. Values	for the	mode 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
				  operations.

		      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 setiomode() manual page for detailed
		    information	on each	I/O mode.

	  mode	    Specifies the read,	write, and execute permissions
		    of the file	to be created (requested by the
		    O_CREAT flag in the	gopen()	interface). If the
		    file already exists, this parameter	is ignored.
		    This parameter is constructed by logically ORing
		    values described in	the sys/mode.h header file.

     DESCRIPTION
	  The gopen() function allows all nodes	in an application to
	  open and share the same file.	The gopen() function performs
	  a global open; all nodes can open the	same file without
	  issuing multiple I/O requests.

	  Other	than the addition of the iomode	parameter, additional
	  return values, and additional	errors,	the semantics of the
	  gopen() function are identical to the	OSF/1 open() function.
	  See the open(2) manual page in the OSF/1 Programmer's	Refer-
	  ence.

	  You can use the gopen() function to specify the I/O mode of
	  a shared file	when it	is opened, rather than requiring an
	  additional call to the setiomode() subroutine. This improves
	  performance when many	nodes open and set the I/O mode	of the
	  same file. You use the iomode	parameter to specify a file's
	  I/O mode. See	the setiomode()	manual page for	a description
	  of the file I/O modes.

	  Use the setiomode() function to change a file's I/O mode
	  after	the file is opened. Use	the iomode() function to
	  return a unit's current I/O mode.

	  The gopen() function globally	synchronizes all nodes in an
	  application. Therefore, all the application's	nodes must
	  call the gopen() function before any node can	continue exe-
	  cuting. In the M_LOG,	M_SYNC,	M_RECORD, and M_GLOBAL I/O
	  modes, closing the file also performs	a global synchronizing
	  operation.

	  When using the OSF/1 fork() function to create new
	  processes, the default I/O mode for the child	process's file
	  descriptors is determined by the file	type (PFS or non-PFS)
	  and the setting of the bootmagic variable PSF_ASYNC_DFLT.
	  For information on how this default I/O mode is determined,
	  see the setiomode() manual page description.

	  When using the OSF/1 dup() function to duplicate a file, the
	  file descriptor for the duplicate file is reset to the I/O
	  mode M_UNIX.

     RETURN VALUES
	  Upon successful completion, gopen() returns the file
	  descriptor representing the open file. If an error occurs,
	  gopen() writes an error message on the standard error	out-
	  put, and causes the calling process to terminate.

	  Upon successful completion, the _gopen() function returns
	  the file descriptor representing the open file. Otherwise,
	  this function	returns	a value	of -1 and sets errno to	indi-
	  cate the error.

     ERRORS
	  If the _gopen() function fails, errno	may be set to one of
	  the error code values	described for the OSF/1	open() func-
	  tion or one of the following values:

	  EINVAL    The	given value for	iomode is not valid.

	  EINVAL    The	file named by the path parameter is not	a reg-
		    ular file.

	  EMIXIO    The	given path is invalid because all nodes	shar-
		    ing	the file have not specified the	same path.

	  EMIXIO    The	given value for	iomode is not valid because
		    all	nodes sharing the file named by	path have not
		    used the same value.

     EXAMPLES
	  The following	example	shows how to use the gopen() function
	  to open a file for writing:

	    #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_LOG,
			  0644);
	       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(), eseek(), estat(), iread(),	iseof(),
	  iwrite(), setiomode()

	  OSF/1	Programmer's Reference:	chmod(2), close(2), dup(2),
	  fcntl(2), lockf(2), lseek(2),	open(2), read(2), stat(2),
	  truncate(2), umask(2), write(2)