Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <io.h>
    #include <fcntl.h>
    #include <sys\stat.h>
    #include <sys\types.h>
    #include <share.h>
    int sopen( const char *filename,
               int access, int share, ... );

Description:
    The sopen function opens a file at the operating system level for shared
    access.  The name of the file to be opened is given by filename.  The
    file will be accessed according to the access mode specified by access.
     When the file is to be created, the optional argument must be given
    which establishes the future access permissions for the file.
     Additionally, the sharing mode of the file is given by the share
    argument.  The optional argument is the file permissions to be used when
     O_CREAT flag is on in the access mode.

    The access mode is established by a combination of the bits defined in
    the <fcntl.h> header file.  The following bits may be set:

    O_RDONLY
        permit the file to be only read.

    O_WRONLY
        permit the file to be only written.

    O_RDWR
        permit the file to be both read and written.

    O_APPEND
        causes each record that is written to be written at the end of the
        file.

    O_CREAT
        has no effect when the file indicated by filename already exists;
        otherwise, the file is created;

    O_TRUNC
        causes the file to be truncated to contain no data when the file
        exists; has no effect when the file does not exist.

    O_BINARY
        causes the file to be opened in binary mode which means that data
        will be transmitted to and from the file unchanged.

    O_TEXT
        causes the file to be opened in text mode which means that
        carriage-return characters are written before any linefeed character
        that is written and causes carriage-return characters to be removed
        when encountered during reads.

    O_NOINHERIT
        indicates that this file is not to be inherited by a child process.

    O_EXCL
        indicates that this file is to be opened for exclusive access.  If
        the file exists and  O_CREAT was also specified then the open will
        fail (i.e., use  O_EXCL to ensure that the file does not already
        exist).

    When neither  O_TEXT nor  O_BINARY are specified, the default value in
    the global variable  _fmode is used to set the file translation mode.
     When the program begins execution, this variable has a value of
     O_TEXT.

     O_CREAT must be specified when the file does not exist and it is to be
    written.

    When the file is to be created ( O_CREAT is specified), an additional
    argument must be passed which contains the file permissions to be used
    for the new file.  The access permissions for the file or directory are
    specified as a combination of bits (defined in the <sys\stat.h> header
    file).

    The following bits define permissions for the owner.

    S_IRWXU
        Read, write, execute/search

    S_IRUSR
        Read permission

    S_IWUSR
        Write permission

    S_IXUSR
        Execute/search permission

    The following bits define permissions for the group.

    S_IRWXG
        Read, write, execute/search

    S_IRGRP
        Read permission

    S_IWGRP
        Write permission

    S_IXGRP
        Execute/search permission

    The following bits define permissions for others.

    S_IRWXO
        Read, write, execute/search

    S_IROTH
        Read permission

    S_IWOTH
        Write permission

    S_IXOTH
        Execute/search permission

    The following bits define miscellaneous permissions used by other
    implementations.

    S_IREAD
        is equivalent to S_IRUSR (read permission)

    S_IWRITE
        is equivalent to S_IWUSR (write permission)

    S_IEXEC
        is equivalent to S_IXUSR (execute/search permission)

    All files are readable with DOS; however, it is a good idea to set
    S_IREAD when read permission is intended for the file.

    The sopen function applies the current file permission mask to the
    specified permissions (see  umask).

    The shared access for the file, share, is established by a combination
    of bits defined in the <share.h> header file.  The following values may
    be set:

    SH_COMPAT
        Set compatibility mode.

    SH_DENYRW
        Prevent read or write access to the file.

    SH_DENYWR
        Prevent write access of the file.

    SH_DENYRD
        Prevent read access to the file.

    SH_DENYNO
        Permit both read and write access to the file.

    You should consult the technical documentation for the DOS system that
    you are using for more detailed information about these sharing modes.

Returns:
    If successful, sopen returns a handle for the file.  When an error
    occurs while opening the file, -1 is returned.  When an error has
    occurred,  errno contains a value indicating the type of error that has
    been detected.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    EACCES
        Access denied because path specifies a directory or a volume ID, or
        sharing mode denied due to a conflicting open.

    EMFILE
        No more handles available (too many open files)

    ENOENT
        Path or file not found


See Also:
    chsize, close, creat, dup, dup2, eof, exec Functions Functions, filelength,
    fileno, fstat, isatty, lseek, open, read, setmode, stat, tell, write,
    umask

Example:
    #include <sys\stat.h>
    #include <sys\types.h>
    #include <fcntl.h>
    #include <share.h>

    void main()
      {
        int handle;

        /* open a file for output                  */
        /* replace existing file if it exists      */

        handle = sopen( "file",
                    O_WRONLY | O_CREAT | O_TRUNC,
                    S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP,
                    SH_DENYWR );

        /* read a file which is assumed to exist   */

        handle = sopen( "file", O_RDONLY, SH_DENYWR );

        /* append to the end of an existing file   */
        /* write a new file if file does not exist */

        handle = sopen( "file",
                    O_WRONLY | O_CREAT | O_APPEND,
                    S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP,
                    SH_DENYWR );
      }

Classification:
    WATCOM

Systems:
    All