Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
open(2)			      System Calls Manual		       open(2)

NAME
       open - open a file

SYNOPSIS
       #include	<sys/types.h>
       #include	<sys/stat.h>
       #include	<fcntl.h>

       int open(const char *path, int oflag,
	    /* mode_t mode */ ...);

DESCRIPTION
       The  open()  function  establishes  the connection between a file and a
       file descriptor.	 It creates an open file description that refers to  a
       file  and  a file descriptor that refers	to that	open file description.
       The file	descriptor is used by other I/O	functions  to  refer  to  that
       file.  The path argument	points to a pathname naming the	file.

       The  open()  function returns a file descriptor for the named file that
       is the lowest file descriptor not currently open	for that process.  The
       open  file  description	is new,	and therefore the file descriptor does
       not share it with any other process in the system.  The FD_CLOEXEC file
       descriptor flag associated with the new file descriptor is cleared.

       The  file  offset  used to mark the current position within the file is
       set to the beginning of the file.

       The file	status flags and file access modes of the open	file  descrip-
       tion is set according to	the value of oflag.

       Values  for  oflag  are	constructed by a bitwise-inclusive-OR of flags
       from the	following list,	defined	in <fcntl.h>.  Applications must spec-
       ify  exactly one	of the first three values (file	access modes) below in
       the value of oflag:

       O_RDONLY	      Open for reading only.

       O_WRONLY	      Open for writing only.

       O_RDWR	      Open for reading and writing. The	result is undefined if
		      this flag	is applied to a	FIFO.

       Any combination of the following	may be used:

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

       O_CREAT	      If the file exists, this flag has	no  effect  except  as
		      noted  under  O_EXCL below.  Otherwise, the file is cre-
		      ated with	the user ID of the file	set to	the  effective
		      user ID of the process.  The group ID of the file	is set
		      to the effective group IDs of the	 process,  or  if  the
		      S_ISGID bit is set in the	directory in which the file is
		      being created, the file's	group ID is set	to  the	 group
		      ID  of its parent	directory.  If the group ID of the new
		      file does	not match the effective	group ID or one	of the
		      supplementary  groups  IDs,  the S_ISGID bit is cleared.
		      The access permission bits  (see	<sys/stat.h>)  of  the
		      file mode	are set	to the value of	mode, modified as fol-
		      lows (see	creat(2)): a bitwise-AND is performed  on  the
		      file-mode	bits and the corresponding bits	in the comple-
		      ment of the process' file	mode creation mask.  Thus, all
		      bits  set	 in the	process's file mode creation mask (see
		      umask(2))	are correspondingly cleared in the file's per-
		      mission mask.  The "save text image after	execution bit"
		      of the mode is cleared (see chmod(2)).  O_SYNC Write I/O
		      operations on the	file descriptor	complete as defined by
		      synchronized I/O file  integrity	completion   (see  fc-
		      ntl(5)  definition of O_SYNC.)  When bits	other than the
		      file permission bits are set, the	effect is unspecified.
		      The  mode	 argument  does	not affect whether the file is
		      open for reading,	writing	or for both.

       O_DSYNC	      Write I/O	operations on the file descriptor complete  as
		      defined by synchronized I/O data integrity completion.

       O_EXCL	      If  O_CREAT and O_EXCL are set, open() fails if the file
		      exists.  The check for the existence of the file and the
		      creation of the file if it does not exist	is atomic with
		      respect to other processes executing open()  naming  the
		      same  filename  in  the  same  directory with O_EXCL and
		      O_CREAT set.  If O_CREAT is not set, the effect is unde-
		      fined.

       O_LARGEFILE    If  set, the offset maximum in the open file description
		      is the largest value that	can be	represented  correctly
		      in an object of type off64_t.

       O_NOCTTY	      If  set  and  path  identifies a terminal	device,	open()
		      does not cause the terminal device to  become  the  con-
		      trolling terminal	for the	process.

       O_NONBLOCK or O_NDELAY
		      These  flags may affect subsequent reads and writes (see
		      read(2) and write(2)).  If both O_NDELAY and  O_NONBLOCK
		      are set, O_NONBLOCK takes	precedence.

		      When opening a FIFO with O_RDONLY	or O_WRONLY set:

		      If O_NONBLOCK or O_NDELAY	is set:
			     An	open() for reading only	returns	without	delay.
			     An	open() for writing only	returns	an error if no
			     process currently has the file open for reading.

		      If O_NONBLOCK and	O_NDELAY are clear:
			     An	open() for reading only	blocks until a process
			     opens the file for	writing.  An open() for	 writ-
			     ing  only	blocks	until a	process	opens the file
			     for reading.

		      When opening a block special or character	 special  file
		      that supports non-blocking opens:

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

		      If O_NONBLOCK and	O_NDELAY are clear:
			     The  open()  function  blocks until the device is
			     ready or available	before returning.

		      Otherwise, the behavior of O_NONBLOCK  and  O_NDELAY  is
		      unspecified.

       O_RSYNC	      Read  I/O	 operations on the file	descriptor complete at
		      the same level of	integrity as specified by the  O_DSYNC
		      and  O_SYNC  flags.  If both O_DSYNC and O_RSYNC are set
		      in oflag,	all I/O	operations on the file descriptor com-
		      plete as defined by synchronized I/O data	integrity com-
		      pletion.	If both	O_SYNC and O_RSYNC are set  in	oflag,
		      all  I/O	operations  on the file	descriptor complete as
		      defined by synchronized I/O file integrity completion.

       O_SYNC	      If O_SYNC	is set on a regular file, writes to that  file
		      cause  the  process to block until the data is delivered
		      to the underlying	hardware.

       O_TRUNC	      If the file exists and is	a regular file,	and  the  file
		      is successfully opened O_RDWR or O_WRONLY, its length is
		      truncated	to 0 and the mode and owner are	unchanged.  It
		      has  no  effect on FIFO special files or terminal	device
		      files. Its effect	on other file types is implementation-
		      dependent.  The result of	using O_TRUNC with O_RDONLY is
		      undefined.

       If O_CREAT is set and the file did not previously exist,	upon  success-
       ful  completion,	 open()	 marks	for update the st_atime, st_ctime, and
       st_mtime	fields of the file and the st_ctime and	st_mtime fields	of the
       parent directory.

       If  O_TRUNC  is	set and	the file did previously	exist, upon successful
       completion, open() marks	for update the st_ctime	and st_mtime fields of
       the file.

       If  path	refers to a STREAMS file, oflag	may be constructed from	O_NON-
       BLOCK or	O_NODELAY OR-ed	with either  O_RDONLY,	O_WRONLY,  or  O_RDWR.
       Other flag values are not applicable to STREAMS devices and have	no ef-
       fect on them.  The values O_NONBLOCK and	O_NODELAY affect the operation
       of  STREAMS  drivers  and  certain  functions  (see read(2), getmsg(2),
       putmsg(2), and write(2))	applied	to file	 descriptors  associated  with
       STREAMS	files.	 For STREAMS drivers, the implementation of O_NONBLOCK
       and O_NODELAY is	device-specific.

       When open() is invoked to open a	named stream, and  the	connld	module
       (see  connld(7M))  has been pushed on the pipe, open() blocks until the
       server process has issued an I_RECVFD ioctl() (see streamio(7I))	to re-
       ceive the file descriptor.

       If  path	 names the master side of a pseudo-terminal device, then it is
       unspecified whether open() locks	the slave side so that	it  cannot  be
       opened.	 Portable  applications	 must call unlockpt(3C)	before opening
       the slave side.

       If path is a symbolic link and O_CREAT and O_EXCL are set, the link  is
       not followed.

       Certain	flag  values  can  be set following open() as described	in fc-
       ntl(2).

       The largest value that can be represented correctly  in	an  object  of
       type  off_t  is	established as the offset maximum in the open file de-
       scription.

RETURN VALUES
       Upon successful completion, the function	opens the file	and  return  a
       non-negative  integer  representing the lowest numbered unused file de-
       scriptor.  Otherwise, -1	is returned and	errno is set to	 indicate  the
       error.  No files	are created or modified	if the function	returns	-1.

ERRORS
       The open() function fails if:

       EACCES	      Search  permission  is denied on a component of the path
		      prefix, or the file exists and the permissions specified
		      by  oflag	 are  denied,  or  the file does not exist and
		      write permission is denied for the parent	 directory  of
		      the  file	 to  be	 created,  or O_TRUNC is specified and
		      write permission is denied.

       EDQUOT	      The file does not	exist, O_CREAT is specified,  and  ei-
		      ther  the	 directory  where  the new file	entry is being
		      placed cannot be extended	because	the  user's  quota  of
		      disk  blocks  on that file system	has been exhausted, or
		      the user's quota of inodes on the	file system where  the
		      file is being created has	been exhausted.

       EEXIST	      O_CREAT and O_EXCL are set, and the named	file exists.

       EINTR	      A	signal was caught during open().

       EFAULT	      path points to an	illegal	address.

       EIO	      The  path	 argument names	a STREAMS file and a hangup or
		      error occurred during the	open().

       EISDIR	      The  named  file	is  a  directory  and  oflag  includes
		      O_WRONLY or O_RDWR.

       ELOOP	      Too  many	 symbolic  links were encountered in resolving
		      path.

       EMFILE	      OPEN_MAX file descriptors	 are  currently	 open  in  the
		      calling process.

       EMULTIHOP      Components  of  path  require hopping to multiple	remote
		      machines and the file system does	not allow it.

       ENAMETOOLONG   The length of the	path argument exceeds  PATH_MAX	 or  a
		      pathname component is longer than	NAME_MAX.

       ENFILE	      The  maximum allowable number of files is	currently open
		      in the system.

       ENOENT	      O_CREAT is not set and the named file does not exist; or
		      O_CREAT is set and either	the path prefix	does not exist
		      or the path argument points to an	empty string.

       ENOLINK	      path points to a remote machine, and the	link  to  that
		      machine is no longer active.

       ENOSR	      The  path	 argument  names  a STREAMS-based file and the
		      system is	unable to allocate a STREAM.

       ENOSPC	      The directory or file system that	would contain the  new
		      file  cannot  be	expanded, the file does	not exist, and
		      O_CREAT is specified.

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

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

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

       EOPNOTSUPP     An attempt was made to open a path that corresponds to a
		      AF_UNIX socket.

       EOVERFLOW      The named	file is	a regular file and either  O_LARGEFILE
		      is  not  set  and	 the size of the file cannot be	repre-
		      sented correctly in an object of type off_t or  O_LARGE-
		      FILE  is	set  and the size of the file cannot be	repre-
		      sented correctly in an object of type off64_t.

       EROFS	      The named	file resides on	a read-only  file  system  and
		      either  O_WRONLY,	 O_RDWR, O_CREAT (if file does not ex-
		      ist), or O_TRUNC is set in the oflag argument.

       The open() function may fail if:

       EAGAIN	      The path argument	names the slave	side of	a  pseudo-ter-
		      minal device that	is locked.

       EINVAL	      The value	of the oflag argument is not valid.

       ENAMETOOLONG   Pathname	resolution  of a symbolic link produced	an in-
		      termediate result	whose length exceeds PATH_MAX.

       ENOMEM	      The path argument	names a	STREAMS	file and the system is
		      unable to	allocate resources.

       ETXTBSY	      The  file	is a pure procedure (shared text) file that is
		      being executed and oflag is O_WRONLY or O_RDWR.

USAGE
       The open() function has an  explicit  64-bit  equivalent.   See	inter-
       face64(5).

       Note that using open64()	is equivalent to using open() with O_LARGEFILE
       set in oflag.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +---------------+-------------------+
       |ATTRIBUTE TYPE |  ATTRIBUTE VALUE  |
       +---------------+-------------------+
       |MT-Level       | Async-Signal-Safe |
       +---------------+-------------------+
SEE ALSO
       intro(2), chmod(2),  close(2),  creat(2),  dup(2),  exec(2),  fcntl(2),
       getmsg(2),   getrlimit(2),   lseek(2),	putmsg(2),  read(2),  stat(2),
       umask(2),  write(2),  unlockpt(3C),  attributes(5),  fcntl(5),	inter-
       face64(5), stat(5), connld(7M), streamio(7I)

NOTES
       Hierarchical  Storage Management	(HSM) file systems can sometimes cause
       long delays when	opening	a file,	since HSM files	must be	recalled  from
       secondary storage.

				  28 Dec 1996			       open(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=open&sektion=2&manpath=SunOS+5.6>

home | help