@node open, io
@subheading Syntax

@example
#include <fcntl.h>
#include <sys/stat.h> /* for mode definitions */

int open(const char *file, int mode /*, int permissions */);
@end example

@subheading Description

This function opens the named @var{file} in the given @var{mode}, which
is any combination of the following:

@table @code

@item O_RDONLY

The file is opened for reading.

@item O_WRONLY

The file is opened for writing.

@item O_RDWR

The file is opened for both reading and writing.

@item O_CREAT

If the file does not exist, it is created. @xref{creat}.

@item O_TRUNC

If the file does exist, it is truncated to zero bytes.

@item O_EXCL

If the file exists, and @code{O_CREAT} is also specified, the
@code{open} call will fail. 

@item O_APPEND

The file pointer is positioned at the end of the file before each write. 

@item O_TEXT

The file is opened in text mode, meaning that Ctrl-M characters are
stripped on reading and added on writing as needed.  The default mode is
specified by the @code{_fmode} variable @ref{_fmode}. 

@item O_BINARY

The file is opened in binary mode.

When called to open the console in binary mode, @code{open} will disable
the generation of @code{SIGINT} when you press @kbd{Ctrl-C}
(@kbd{Ctrl-Break} will still cause @code{SIGINT}), because many programs
that use binary reads from the console will also want to get the
@samp{^C} characters.  You can use the @code{__djgpp_set_ctrl_c} library
function (@pxref{__djgpp_set_ctrl_c}) if you want @kbd{Ctrl-C} to
generate interrupts while console is read in binary mode.

@end table

If the file is created by this call, it will be given the read/write
permissions specified by @var{permissions}, which may be any combination
of these values:

@table @code

@item S_IRUSR

The file is readable.  This is always true for MS-DOS.

@item S_IWUSR

The file is writable.

@end table

Other @code{S_I*} values may be included, but they will be ignored.

You can specify the share flags (a DOS specific feature) in @var{mode}.
And you can indicate default values for the share flags in
@code{__djgpp_share_flags}. @xref{__djgpp_share_flags}.

@subheading Return Value

If successful, the file descriptor is returned.  On error, a negative
number is returned and @code{errno} is set to indicate the error. 

@subheading Portability

@portability !ansi, posix

@subheading Example

@example
int q = open("/tmp/foo.dat", O_RDONLY|O_BINARY);
@end example

@c ---------------------------------------------------------------------------
@node __djgpp_share_flags, io

@subheading Syntax

@example
#include <fcntl.h>

int __djgpp_share_flags = ...;
@end example

@subheading Description

This variable controls the share flags used by @code{open} (and hence
@code{fopen}) when opening a file.

If you assign any value other than 0 to this variable libc will use
that value for the sharing bits when if calls DOS to open the file.
But if you specify any share flag in the @code{open} call then these
flags will remain untouched. In this way @code{__djgpp_share_flags}
acts just like a default and by default is 0 ensuring maximum
compatibility with older versions of djgpp.

If you don't know how the share flags act consult any DOS reference. They
allow to share or protect a file when it's opened more than once by the
same task or by two or more tasks. The exact behavior depends on the exact
case. One interesting thing is that when the file is opened by two tasks
under Windows the results are different if you use Windows 3.1 or Windows 95.
To add even more complexity Windows 3.1 is affected by @code{SHARE.EXE}.

The available flags are:

@table @code

@item SH_COMPAT	0x0000

That's the compatible mode.

@item SH_DENYRW	0x0010

Deny read and deny write.

@item SH_DENYWR	0x0020

Deny write.

@item SH_DENYRD	0x0030

Deny read.

@item SH_DENYNO	0x0040

No deny.

@end table

Of course these flags are DOS specific and doesn't exist under other OSs;
and as you can imagine @code{__djgpp_share_flags} is djgpp specific.

@xref{open}.
@xref{fopen}.


@subheading Portability

@portability !ansi, !posix