open: open a file

SYNOPSIS

int open(const char *path, int flags);

int open(const char *path, int flags, int mode);

DESCRIPTION

This system call implements the POSIX open function, which attempts to open a file given its pathname.

PARAMETERS

path

The pathname of the file to open. Under MOSS, there are several different ``types'' of files that can be opened using this function and accessed with any of the file I/O functions:

• If a DOS file of the specified name can be found, it is opened and associated with the returned file descriptor. However, note that the MOSS file descriptor returned does not necessarily correspond to the DOS file descriptor used by MOSS itself to invoke DOS's file operations.
• If no DOS file of the specified name can be found, but an ``embedded file'' attached to the MOSS executable exists with a name exactly matching the name requested, then the embedded file is opened and associated with the file descriptor. The program can then use the embedded file like any other file, including seeking around in the file; however, embedded files cannot be written to or deleted.
• If you specify the ``magic'' pathname `/dev/mem', you will receive a file handle that you can later use to mmap parts of physical memory into the program's directly-accessible address space. Currently the other ``normal'' file operations, such as read, write, and seek, are not implemented for /dev/mem.

flags

The flags argument works basically as under POSIX or BSD; MOSS will emulate the open modes not supported directly by DOS. However, note that due to this emulation, the open operation may not be quite as atomic as it is supposed to be under POSIX systems.

For example, if you use the flags `O_CREAT | O_EXCL', MOSS must first check to see if the file exists, and then if it doesn't, create it using DOS's ``create file'' call. In multitasking environments that support DOS, it is possible that the file could be created after MOSS checks to see if it exists but before the call to create the file. In that case, the open will succeed and the existing file will be truncated, which violates the POSIX atomicity rules for open. Well, too bad: this is DOS.

Also, the O_APPEND flag is only partly supported. If you specify O_APPEND, then the file pointer will be positioned at the end of the file initially during open, but it is not re-positioned at the end prior to each write, as specified by POSIX. Again, this is generally good enough for typical situations, but it is ``not quite right'' in its semantics.

mode

When you create a file under MOSS, you may specify a normal POSIX permission mask. However, only the user-writable bit (S_IWUSR) will be used to determine whether the DOS file will be read/write or read-only; the other bits in the mode are ignored.

RETURN VALUE

Returns the opened file descriptor if successful, or -1 on error, in which case errno indicates the error.