unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



open(2)								      open(2)



NAME

  open,	creat -	Opens a	file for reading or writing

SYNOPSIS

  #include <&lt;fcntl.h>&gt;
  #include <&lt;sys/stat.h>&gt;
  #include <&lt;sys/types.h>&gt;

  int open (
	  const	char *path,
	  int oflag [ ,
	  mode_t mode ]	);

  int creat (
	  const	char *path,
	  mode_t mode );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  creat():  POSIX.1, XPG4, XPG4-UNIX

  open():  POSIX.1, XPG4, XPG4-UNIX

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  path
      Specifies	the file to be opened or created.  If the path parameter
      refers to	a symbolic link, the open() function opens the file pointed
      to by the	symbolic link.

  oflag
      Specifies	the type of access, special open processing, the type of
      update, and the initial state of the open	file. The parameter value is
      constructed by logically OR-ing special open processing flags.  These
      flags are	defined	in the fcntl.h header file and are described below.

  mode
      Specifies	the read, write, and execute permissions of the	file to	be
      created (requested by the	O_CREAT	flag in	the open() interface).	If
      the file already exists, this parameter is ignored. This parameter is
      constructed by logically OR-ing values described in the sys/mode.h
      header file.




DESCRIPTION

  The following	two function calls are equivalent:


  creat(path, mode);

  open(path, O_WRONLY |	O_CREAT	| O_TRUNC, mode);

  The open() and creat() functions establish a connection between the file
  named	by the path parameter and a file descriptor.  Subsequent I/O func-
  tions, such as  read() and write(), use the open file	descriptor to access
  the file.

  The file descriptor returned for a file is the lowest	file descriptor	not
  previously opened for	that process.  In most cases, a	process	cannot have
  more than OPEN_MAX file descriptors open simultaneously.  The	per-process
  soft descriptor limit	is configurable.  The minimum value is 64.  See
  getrlimit(2) and setrlimit(2).

  The open() and creat() functions suspend the calling process until the cal-
  ling thread is suspended.

  When an open() or creat() function is	called,	the file offset, which marks
  the current position within the file,	is set to the beginning	of the file.
  The new file descriptor is set to remain open	across exec functions (see
  fcntl(2)).

  The file status flags	and file access	flags are designated by	the oflag
  parameter.  The oflag	parameter is constructed by bitwise-inclusive OR-ing
  exactly one of the file access flags with one	or more	of the file status
  flags.

  File Access Flags

  The file access flags, which specify read and	write access are as follows:

  O_RDONLY
      The file is open only for	reading.

  O_WRONLY
      The file is open only for	writing.

  O_RDWR
      The file is open for reading and writing.

  Only one file	access value (O_RDONLY,	O_WRONLY, or O_RDWR) can be speci-
  fied.	 If exactly no value is	set, the default O_RDONLY is used.

  File Status Flags

  The file status flags, which specify file open processing, are as follows:

  O_CREAT
      If the file exists, this flag has	no effect, except as described under
      the O_EXCL flag. If the file does	not exist, a regular file is created
      with the following characteristics:

	+  The owner ID	of the file is set to the effective user ID of the
	   process.

	+  The group ID	of the file is set to the group	ID of its parent
	   directory.

	   However, when the vfs subsystem attribute sys_v_mode	is set to 1,
	   the group ID	of the file is set either to the group ID of the pro-
	   cess	or, if the S_ISGID bit of the parent directory is set, to the
	   group ID of the parent directory.

	   If the group	ID of the new file does	not match the process's
	   effective group or one of its supplementary group IDs, the S_ISGID
	   bit of the new file is cleared.

	   The access permission bits of the file mode are set to the value
	   of mode as follows:	The corresponding bits are AND-ed with the
	   complement of the file mode creation	mask for the process.

	+  The file permission and attribute bits are set to the value of the
	   mode	parameter, which is modified as	follows:

	   - All bits in the file mode whose corresponding bits	in the file
	     mode creation mask	are set	are cleared.

	   - The set-user ID attribute (S_ISUID	bit) is	cleared.

	   - The set-group ID attribute	(S_ISGID bit) is cleared.

	+  The access control list of the new file is set to WILDCARD (dis-
	   cretionary access to	the file according to traditional UNIX
	   rules).

      To create	a new file, the	calling	process	must have permission to	write
      to the file's parent directory with respect to all access	control	poli-
      cies.

  O_EXCL
      If the file exists and O_EXCL and	O_CREAT	are set, the open will fail.

  O_NOCTTY
      If the path parameter identifies a terminal device, this flag assures
      that the terminal	device does not	become the controlling terminal	for
      the process.

      System V Compatibility

      In the Tru64 UNIX	operating system, O_NOCTTY is set by default and can-
      not be unset.  In	the System V habitat, however, O_NOCTTY	is not set by
      default, and a terminal device can become	the controlling	terminal for
      the process if both of the following conditions are met:

	+  The process does not	already	have a controlling terminal.

	+  The terminal	device pointed to by path is not already a control-
	   ling	terminal.

  O_TRUNC
      If the file does not exist, this flag has	no effect.

      If the file exists, is a regular file, and is successfully opened	with
      O_WRONLY or O_RDWR*, the following occurs:

	+  The length of the file is truncated to 0 (zero).

	+  The owner and group of the file are unchanged.

	+  The set-user	ID attribute of	the file mode is cleared, unless the
	   vfs subsystem variable sys_v_mode is	set to 1.  In this case, the
	   file	length is truncated to 0 and the mode, owner, and group	are
	   not changed.

	+  The set-user	ID attribute of	the file is cleared.

      The open fails if	either of the following	conditions is true:

	+  The file supports enforced record locks and another process has
	   locked a portion of the file.

	+  The file does not allow write access.


      If the oflag parameter also specifies O_SYNC, O_DSYNC, or	O_RSYNC, the
      truncation becomes a synchronous update.

      A	program	can request some control over when updates should be made
      permanent	for a regular file that	is opened for write access.

      The calling process must have write access to the	file with respect to
      all access policies.

  O_NOFOLLOW
      If this flag is set and the last component of the	pathname is a sym-
      link, open()will fail, even if the symlink points	to a non-existent
      file.

  File status flags that specify special processing for	subsequent reads and
  writes of the	open file are as follows:

  O_SYNC
      If set, and if the vfs subsystem variable	strict_posix_osync is set to
      1	(enabled), updates and writes to regular files and block devices will
      synchronously update data	and file attribute information.	 When a	func-
      tion that	performs an O_SYNC synchronous update (a write() system	call
      when O_SYNC is set) returns, the calling process is assured that all
      data and file attribute information has been written to permanent
      storage, even if a file is also open for deferred	(asynchronous)
      update.  If the strict_posix_osync variable is set to 0, updates and
      writes to	regular	files and block	devices	synchronously update only
      data (see	the O_DSYNC flag).

  O_DSYNC
      If set, updates and writes to regular files and block devices will syn-
      chronously update	only the data and file attributes that are required
      to retrieve data.	 For example, this occurs when a file is extended.
      When a function returns that performs an O_DSYNC synchronous update (a
      write() system call when O_DSYNC is set),	the calling process is
      assured that all data has	been written to	permanent storage.  However,
      using O_DSYNC does not guarantee that file-control information, such as
      owner and	modification time, is updated to permanent storage.

  O_RSYNC
      If set and if O_DSYNC is set, enables synchronized I/O data integrity
      for read operations.  The	calling	process	is assured that	all pending
      file data	writes are written to permanent	storage	prior to a read.

      If set, and if O_SYNC is set, enables synchronized I/O file integrity
      for read operations.  The	calling	process	is assured that	all data and
      file attribute information is written to permanent storage prior to a
      read.

      If O_RSYNC stoppp	is used	alone, it has no effect.

  O_APPEND
      If set, the file pointer is set to the end of the	file prior to each
      write.

  O_NONBLOCK, O_NDELAY
      If set, the call to open() will not block, and subsequent	read() or
      write() operations on the	file will be nonblocking.

  AdvFS-only File Flags

  The following	file access and	status flags are used only with	AdvFS, and
  are ignored by all other file	systems.

  O_DIRECTIO
      Enables direct I/O on a file.  Also enables direct I/O for all
      processes	that have opened the file.  Note that you cannot enable
      direct I/O for a data logging file or for	a file that is mmapped.	 In
      addition,	you cannot mmap	a file that has	direct I/O enabled.

  General Notes	on oflag Parameter Flag	Values

  The effect of	O_CREAT	is immediate.

  When opening a FIFO with O_RDONLY:

    +  If O_NDELAY or O_NONBLOCK is not	set, the open()	function is blocked
       until another process opens the file for	writing. If the	file is
       already open for	writing	(even by the calling process), the open()
       function	returns	immediately.

    +  If O_NDELAY or O_NONBLOCK is set, the open() function returns immedi-
       ately.

  When opening a FIFO with O_WRONLY:

    +  If O_NDELAY or O_NONBLOCK is not	set, the open()	function is blocked
       until another process opens the file for	reading.  If the file is
       already open for	reading	(even by the calling process), the open()
       function	returns	without	delay.

    +  If O_NDELAY or O_NONBLOCK is set, the open() function returns an	error
       if no process currently has the file open for reading.

  When opening a block special or character special file that supports non-
  blocking opens (such as from a terminal device):

    +  If O_NDELAY or O_NONBLOCK is not	set, the open()	function is blocked
       until the device	is ready or available.

    +  If O_NDELAY or O_NONBLOCK is set, the open() function returns without
       waiting for the device to be ready or available.	Subsequent behavior
       of the device is	device-specific.

  When opening a STREAMS file, oflag may be constructed	from O_NDELAY or
  O_NONBLOCK OR-ed with	either O_RDONLY, O_WRONLY or O_RDWR.  Other flag
  values are not applicable to STREAMS devices and have	no effect on them.
  The value of O_NDELAY	or NON_BLOCK affects the operation of STREAMS drivers
  and certain system calls. See	read(2), getmsg(2), putmsg(2), and write(2).
  For drivers, the implementation of O_NDELAY or NON_BLOCK is device-
  specific.  Different STREAMS device drivers may treat	this option dif-
  ferently.

RESTRICTIONS

  Since	a file newly created by	creat()	is write_only, an fdopen() call	using
  the r+ parameter fails if it follows a creat() call.	A solution to this
  problem is to	create the file	using a	call that adheres to the following
  format:

  open(path, O_RDWR | O_CREAT, 0666);


RETURN VALUES

  On successful	completion, the	open() and creat() functions return the	file
  descriptor, which is a nonnegative integer.  If the open fails, a value of
  -1 is	returned and errno is set to indicate the error.

ERRORS

  If the open()	or creat() function fails, errno may be	set to one of the
  following values:

  [EACCES]
	  One of the following occurred:  Search permission is denied on a
	  component of the path	prefix,	the type of access specified by	the
	  oflag	parameter is denied for	the named file,	the file does not
	  exist	and write permission is	denied for the parent directory, or
	  O_TRUNC is specified and write permission is denied.

  [EAGAIN]
	  The O_TRUNC flag is set, the named file exists with enforced record
	  locking enabled, and record locks are	put on the file.

  [EBUSY] The named file is a block device file	and the	block device is	in
	  use by a mounted file	system.

  [EDQUOT]
	  The directory	in which the entry for the new link is being placed
	  cannot be extended, because the quota	of disk	blocks (or inodes
	  that are defined for the user	on the file system containing the
	  directory) has been exhausted.

  [EEXIST]
	  The O_CREAT and O_EXCL flags are set and the named file exists.

  [EFAULT]
	  The path parameter is	an invalid address.

  [EINTR] A signal was caught by the open() function.

  [EINVAL]
	  The owner or group ID	is not a value supported by this implementa-
	  tion,	or the O_DIRECTIO flag was specified and the file is already
	  opened for atomic write data logging or is mmapped.

  [EIO]	  [Tru64 UNIX] O_CREAT was requested and an I/O	error occurred when
	  updating the directory.

  [EISDIR]
	  The named file is a directory	and write access was requested.

	  In a System V	habitat, the named file	is a directory and the oflag
	  permission is	write or read/write.

  [ELOOP] Too many symbolic links were encountered in translating path.

  [EMFILE]

	  The system limit for open file descriptors per process has already
	  reached the OPEN_MAX limit, or the per-process soft descriptor
	  limit	has already been reached.

  [ENAMETOOLONG]
	  The length of	the path string	exceeds	PATH_MAX or a pathname com-
	  ponent is longer than	NAME_MAX.

  [ENETUNREACH]
	  The path parameter points to a remote	machine	and the	link to	that
	  machine is no	longer active.

  [ENFILE]
	  The system file table	is full.

  [ENOENT]
	  One of the following applies:	The O_CREAT flag is not	set and	the
	  named	file does not exist, the O_CREAT is set	and the	path prefix
	  does not exist, or the path parameter	points to an empty string.

  [ENOMEM]
	  The system was unable	to allocate kernel memory for more file
	  descriptors.

  [ENOSPC]
	  The directory	that would contain the new file	cannot be extended,
	  the file does	not exist, and O_CREAT is requested.

  [ENOSR] Unable to allocate a stream.

  [ENOTDIR]
	  A component of the path prefix is not	a directory.

  [ENXIO] One of the following applies:

	  The named file is a character	special	or block special file and the
	  device associated with this special file does	not exist.

	  The named file is a multiplexed special file and the channel number
	  is outside of	the valid range, or no more channels are available.

	  The O_NONBLOCK flag is set, the named	file is	a FIFO,	O_WRONLY is
	  set, and no process has the file open	for reading.

	  A STREAMS module or driver open routine failed.

  [EOPNOTSUPP]
	  The named file is a socket bound to the file system (a UNIX domain
	  socket) and cannot be	opened.

  [EROFS] The named file resides on a read-only	file system and	write access
	  is required.

  For NFS file access, if the open() or	creat()	function fails,	errno may be
  set to one of	the following values:

  [EREMOTE]
	  A server attempted to	handle an NFS request by generating a request
	  to another NFS server, which is not allowed.

  [ESTALE]
	  A stale NFS file handle exists.  One of the following	occurred: An
	  open file was	deleted	by the server or another client, the server
	  unmounted or unexported the remote directory,	or the server
	  unmounted or unexported the directory	that contains an open file.

  [ETIMEDOUT]
	  A connection time-out	occurred.  For files that are mounted with
	  the soft option, the server is down or there is a network problem.

RELATED	INFORMATION

  Functions: chmod(2), close(2), fcntl(2), getmsg(2), lseek(2),	putmsg(2),
  read(2), stat(2), truncate(2), umask(2), write(2), lockf(3)

  Standards: standards(5)