sopen()

Open a file for shared access

Synopsis:

#include <unistd.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <share.h>

int sopen( const char* filename,
           int access, 
           int share,
           ... );

Library:

libc

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 is accessed according to the access mode specified by access.

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; you must provide this when the file is to be created.

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

Cause 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 doesn't exist.

O_EXCL

Indicates that this file is to be opened for exclusive access. If the file exists and O_CREAT is also specified, the open fails (that is, use O_EXCL to ensure that the file doesn't already exist).

O_CREAT must be specified when the file doesn't exist.

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. These are defined in the <sys/stat.h> header 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 to the file.

SH_DENYRD

Prevent read access to the file.

SH_DENYNO

Permit both read and write access to the file.

Note that

open( path, oflag, ... );

is the same as:

sopen( path, oflag, SH_COMPAT, ... );

The sopen() function ignores advisory locks that may have been set by the fcntl() function.

Returns:

A descriptor for the file, or -1 if an error occurs while opening the file (errno is set).

Errors:

EACCES

Search permission is denied on a component of the path prefix, or the file exists and the permissions specified by access are denied, or the file doesn't exist and write permission is denied for the parent directory of the file to be created.

EBUSY

Sharing mode was denied due to a conflicting open.

EISDIR

The named file is a directory, and the access argument specifies write-only or read/write access.

ELOOP

Too many levels of symbolic links or prefixes.

EMFILE

No more descriptors available (too many open files).

ENOENT

Path or file not found.

ENOSYS

The sopen() function isn't implemented for the filesystem specified in path.

Examples:

#include <stdlib.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <fcntl.h>
#include <share.h>

int main( void )
  {
    int filedes ;

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

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

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

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

    /* append to the end of an existing file   */
    /* write a new file if file doesn't exist */

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

Classification:

Unix

See also:

chsize(), close(), creat(), dup(), dup2(), errno, eof(), execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), fcntl(), fileno(), fstat(), isatty(), lseek(), open(), read(), stat(), tell(), umask(), write()