### _sopen -- Open Shared File

Format

>     #include <fcntl.h>
>     #include <sys\stat.h>
>     #include <share.h>
>     #include <io.h>
>     int _sopen(char *pathname, int oflag, int shflag , int pmode);

Language Level: Extension
_sopen opens the file specified by pathname and prepares the file for subsequent shared reading or writing as defined by oflag and shflag. The oflag is an integer expression formed by combining one or more of the constants defined in <fcntl.h>. When more than one constant is given, the constants are joined with the OR operator (|).

Oflag | Meaning
O_APPEND | Reposition the file pointer to the end of the file before every write operation.
O_CREAT | Create and open a new file. This flag has no effect if the file specified by pathname exists.
O_EXCL | Return an error value if the file specified by pathname exists. This flag applies only when used with O_CREAT.
O_RDONLY | Open the file for reading only. If this flag is given, neither O_RDWR nor O_WRONLY can be given.
O_RDWR | Open the file for both reading and writing. If this flag is given, neither O_RDONLY nor O_WRONLY can be given.
O_TRUNC | Open and truncate an existing file to 0 length. The file must have write permission. The contents of the file are destroyed. Do not specify O_TRUNC with O_RDONLY.
O_WRONLY | Open the file for writing only. If this flag is given, neither O_RDONLY nor O_RDWR can be given.
O_BINARY | Open the file in binary (untranslated) mode.
O_TEXT | Open the file in text (translated) mode. (See Stream Processing for a description of text and binary mode.)

The shflag argument is one of the following constants, defined in <share.h>:

Shflag | Meaning
SH_DENYRW | Deny read and write access to file.
SH_DENYWR | Deny write access to file.
SH_DENYRD | Deny read access to file.
SH_DENYNO | Permit read and write access.

There is no default value for the shflag.

The pmode argument is required only when you specify O_CREAT. If the file does not exist, pmode specifies the permission settings of the file, which are set when the new file is closed for the first time. If the file exists, the value of pmode is ignored. The pmode must be one of the following values, defined in <sys\stat.h>:

Value | Meaning
S_IWRITE | Writing permitted
S_IREAD | Reading permitted
S_IREAD | S_IWRITE | Reading and writing permitted.

If write permission is not given, the file is read-only.

On the OS/2 and Windows operating systems, all files are readable; you cannot give write-only permission. Thus, the modes S_IWRITE and S_IREAD | S_IWRITE are equivalent. Specifying a pmode of S_IREAD is similar to making a file read-only with the ATTRIB system command.

_sopen applies the current file permission mask to pmode before setting the permissions. (See umask -- Sets File Mask of Current Process for information on file permission masks.)

Return Value
_sopen returns a file handle for the opened file. A return value of -1 indicates an error, and errno is set to one of the following values:

Value | Meaning
EACCESS | The given path name is a directory, but the file is read-only and an attempt was made to open it for writing, or a sharing violation occurred.
EEXIST | The O_CREAT and O_EXCL flags are specified, but the named file already exists.
EMFILE | No more file handles are available.
ENOENT | The file or path name was not found.
EINVAL | An incorrect argument was passed.
EOS2ERR | The call to the operating system was not successful.

Example
This example opens the file sopen.dat for shared reading and writing using _sopen. It then opens the file for shared reading.

    #include <io.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <fcntl.h>
    #include <share.h>

    #define FILENAME "sopen.dat"

    int main(void)
    {
       int fh1,fh2;

       printf("Creating file.\n");
       system("echo Sample Program > " FILENAME);

       /* share open the file for reading and writing                 */
       if (-1 == (fh1 = _sopen(FILENAME, O_RDWR, SH_DENYNO))) {
          perror("sopen failed");
          remove(FILENAME);
          return EXIT_FAILURE;
       }
       /* share open the file for reading only                        */
       if (-1 == (fh2 = _sopen(FILENAME, O_RDONLY, SH_DENYNO))) {
          perror("sopen failed");
          close(fh1);
          remove(FILENAME);
          return EXIT_FAILURE;
       }
       printf("File successfully opened for sharing.\n");
       close(fh1);
       close(fh2);
       remove(FILENAME);
       return 0;

       /****************************************************************
          The output should be:

          Creating file.
          File successfully opened for sharing.
       ****************************************************************/
    }

Stream Processing

close -- Close File Associated with Handle
creat -- Create New File
open -- Open File
fdopen -- Associated Input or Output With File
fopen -- Open Files
_sopen -- Open Shared File
umask -- Sets File Mask of Current Process
<fcntl.h>
<io.h>
<share.h>
<sys\stat.h>