SOPEN(DOS) UNIX System V SOPEN(DOS)
Name
sopen - Opens a file for shared reading or writing.
Syntax
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <share.h>
#include <io.h>
int sopen(path, oflag, shflag[, pmode])
char *path;
int oflag;
int shflag;
int pmode;
Description
The sopen function opens the file specified by path and
prepares the file for subsequent shared reading or writing,
as defined by oflag and shflag. The integer expression oflag
is formed by combining one or more of the following manifest
constants, defined in the file fcntl.h. When more than one
manifest constant is given, the constants are joined with
the OR operator ( | ).
Constant Meaning
O_APPEND Repositions the file pointer to the
end of the file before every write
operation.
O_BINARY Opens file in binary (untranslated)
mode. (See fopen for a description
of binary mode.)
O_CREAT Creates and opens a new file. This
has no effect if the file specified
by path exists.
O_EXCL Returns an error value if the file
specified by path exists. This
applies only when used with O_CREAT.
O_RDONLY Opens file for reading only. If this
flag is given, neither the O_RDWR
flag nor the O_WRONLY flag can be
given.
O_RDWR Opens file for both reading and
writing. If this flag is given,
neither O_RDONLY nor O_WRONLY can be
given.
O_TEXT Opens file in text (translated)
mode. (See fopen for a description
of text mode.)
O_TRUNC Opens and truncates an existing file
to 0 bytes. The file must have write
permission; the contents of the file
are destroyed.
O_WRONLY Opens file for writing only. If this
flag is given, neither O_RDONLY nor
O_RDWR can be given.
O_TRUNC destroys the entire contents of an existing file.
Use it with care.
The argument shflag is a constant expression consisting of
one of the following manifest constants, defined in share.h.
If SHARE.COM (or SHARE.EXE for some versions of DOS) is not
installed, DOS ignores the sharing mode. (See your system
documentation for detailed information about sharing modes.)
Constant Meaning
SH_COMPAT Sets compatibility mode (not available in OS/2)
SH_DENYRW Denies read and write access to file
SH_DENYWR Denies write access to file
SH_DENYRD Denies read access to file
SH_DENYNO Permits read and write access
The sopen function should be used only under OS/2 and DOS
Versions 3.0 and later. Under earlier versions of DOS, the
shflag argument is ignored.
The pmode argument is required only when O_CREAT is
specified. If the file does not exist, pmode specifies the
file's permission settings, which are set when the new file
is closed for the first time. Otherwise, the pmode argument
is ignored. The pmode argument is an integer expression that
contains one or both of the manifest constants S_IWRITE and
S_IREAD, defined in sys/stat.h. When both constants are
given, they are joined with the OR operator ( | ).
The meaning of the pmode argument is as follows:
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.
Under DOS and OS/2, all files are readable; it is not
possible to give write-only permission. Thus the modes
S_IWRITE and S_IREAD | S_IWRITE are equivalent.
Note that under DOS Versions 3.x with SHARE installed, a
problem occurs when opening a new file with sopen under the
following sets of conditions:
+ With oflag set to O_CREAT | O_RDONLY or
O_CREAT | WRONLY, pmode set to S_IREAD, and shflag set
to SH_COMPAT.
+ With oflag set to any combination that includes O_FLAG,
pmode set to S_IREAD, and shflag set to anything other
than SH_COMPAT.
In either case, the operating system will prematurely close
the file during system calls made within sopen, or the
system will generate a sharing violation (INT 24H). To avoid
the problem, open the file with pmode set to S_IWRITE. After
closing the file, call chmod and change the mode back to
S_IREAD. Another way around the problem is to open the file
with pmode set to S_IREAD, oflag set to O_CREAT | O_RDWR,
and shflag set to SH_COMPAT.
The sopen function applies the current file-permission mask
to pmode before setting the permissions (see umask).
Return Value
The sopen function 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
EACCES Given path name is a directory; or the file is read
only but an open for writing was attempted; or a
sharing violation occurred (the file's sharing mode
does not allow the specified operations; OS/2 and DOS
Versions 3.0 and later only).
EEXIST The O_CREAT and O_EXCL flags are specified, but the
named file already exists.
EINVAL An invalid oflag or shflag argument was given.
EMFILE No more file handles available (too many open files).
ENOENT File or path name not found.
See Also
close(S), creat(DOS), fopen(DOS), open(DOS), umask(DOS)
Notes
File-sharing modes will not work correctly for buffered
files, so do not use fdopen to associate a file opened for
sharing (or locking) with a stream.
Example
#include <fcntl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <share.h>
#include <io.h>
extern unsigned char _osmajor;
int fh;
main()
{
/* Open for file sharing: */
if (_osmajor >= 3)
fh = sopen("sopen.c", O_RDWR | O_BINARY, SH_DENYRW);
else
/* Just a regular open */
fh = open("sopen.c", O_RDWR | O_BINARY );
if (fh == -1)
perror("Failure on an attempt to open the file");
else
printf("File opened successfully\n");
if (_osmajor >= 3)
printf("At least version 3.0, sopen used.\n");
else
printf("Pre version 3.0, open used.\n");
}
This program first checks the version of DOS. If the version
is 3.0 or later, it uses sopen to open a file named sopen.c
for sharing.
(printed 7/6/89)