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

NAME
     open, openat -- open or create a file for reading, writing or executing

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <fcntl.h>

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

     int
     openat(int fd, const char *path, int flags, ...);

DESCRIPTION
     The  file	name specified by path is opened for either execution or reading
     and/or writing as specified by the argument flags and the	file  descriptor
     returned  to the calling process.	The flags argument may indicate the file
     is to be created if it does not exist (by specifying the O_CREAT flag).  In
     this case open() and openat() require an additional argument  mode_t  mode,
     and  the  file is created with mode mode as described in chmod(2) and modi-
     fied by the process' umask value (see umask(2)).

     The openat() function is equivalent to the open() function  except  in  the
     case where the path specifies a relative path.  In this case the file to be
     opened is determined relative to the directory associated with the file de-
     scriptor  fd  instead of the current working directory.  The flag parameter
     and the optional fourth parameter correspond exactly to the  parameters  of
     open().  If openat() is passed the special value AT_FDCWD in the fd parame-
     ter, the current working directory is used and the behavior is identical to
     a call to open().

     The flags specified are formed by or'ing the following values

	   O_RDONLY	   open for reading only
	   O_WRONLY	   open for writing only
	   O_RDWR	   open for reading and writing
	   O_EXEC	   open for execute only
	   O_NONBLOCK	   do not block on open
	   O_APPEND	   append on each write
	   O_CREAT	   create file if it does not exist
	   O_TRUNC	   truncate size to 0
	   O_EXCL	   error if create and file exists
	   O_SHLOCK	   atomically obtain a shared lock
	   O_EXLOCK	   atomically obtain an exclusive lock
	   O_DIRECT	   eliminate or reduce cache effects
	   O_FSYNC	   synchronous writes
	   O_SYNC	   synchronous writes
	   O_NOFOLLOW	   do not follow symlinks
	   O_NOCTTY	   don't assign controlling terminal
	   O_TTY_INIT	   restore default terminal attributes
	   O_CLOEXEC	   set FD_CLOEXEC upon open

     Opening  a  file  with O_APPEND set causes each write on the file to be ap-
     pended to the end.  If O_TRUNC is specified and the file exists,  the  file
     is  truncated  to	zero length.  If O_EXCL is set with O_CREAT and the file
     already exists, open() returns an error.  This may be used to  implement  a
     simple  exclusive	access locking mechanism.  If O_EXCL is set and the last
     component of the pathname is a symbolic link, open() will fail even if  the
     symbolic  link  points  to  a non-existent name.  If the O_NONBLOCK flag is
     specified and the open() system call would  result  in  the  process  being
     blocked  for  some  reason  (e.g.,  waiting  for carrier on a dialup line),
     open() returns immediately.  The descriptor remains  in  non-blocking  mode
     for subsequent operations.

     If  O_FSYNC  is used in the mask, all writes will immediately be written to
     disk, the kernel will not cache written data and all writes on the descrip-
     tor will not return until the data to be written completes.

     O_SYNC is a synonym for O_FSYNC required by POSIX.

     If O_NOFOLLOW is used in the mask and the target file passed to open() is a
     symbolic link then the open() will fail.

     When opening a file, a lock with flock(2) semantics can be obtained by set-
     ting O_SHLOCK for a shared lock, or O_EXLOCK for  an  exclusive  lock.   If
     creating  a  file	with  O_CREAT,	the request for the lock will never fail
     (provided that the underlying file system supports locking).

     O_DIRECT may be used to minimize or eliminate the cache effects of  reading
     and writing.  The system will attempt to avoid caching the data you read or
     write.   If  it  cannot avoid caching the data, it will minimize the impact
     the data has on the cache.  Use of this flag can drastically reduce perfor-
     mance if not used with care.

     O_NOCTTY may be used to ensure the OS does not assign this file as the con-
     trolling terminal when it opens a tty  device.   This  is	the  default  on
     FreeBSD,  but  is	present for POSIX compatibility.  The open() system call
     will not assign controlling terminals on FreeBSD.

     O_TTY_INIT may be used to ensure the OS restores  the  terminal  attributes
     when  initially  opening  a  TTY.	 This  is the default on FreeBSD, but is
     present for POSIX compatibility.  The initial call to open() on a TTY  will
     always restore default terminal attributes on FreeBSD.

     O_CLOEXEC	may  be  used to set FD_CLOEXEC flag for the newly returned file
     descriptor.

     If successful, open() returns a non-negative integer,  termed  a  file  de-
     scriptor.	 It  returns  -1  on failure.  The file pointer used to mark the
     current position within the file is set to the beginning of the file.

     When a new file is created it is given the group  of  the	directory  which
     contains it.

     Unless  O_CLOEXEC	flag  was specified, the new descriptor is set to remain
     open across execve(2) system calls; see close(2),	fcntl(2)  and  O_CLOEXEC
     description.

     The  system imposes a limit on the number of file descriptors open simulta-
     neously by one process.  The getdtablesize(2) system call returns the  cur-
     rent system limit.

RETURN VALUES
     If  successful, open() and openat() return a non-negative integer, termed a
     file descriptor.  They return -1 on failure, and set errno to indicate  the
     error.

ERRORS
     The named file is opened unless:

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

     [ENAMETOOLONG]	A component of a pathname exceeded 255 characters, or an
			entire path name exceeded 1023 characters.

     [ENOENT]		O_CREAT is not set and the named file does not exist.

     [ENOENT]		A  component  of  the path name that must exist does not
			exist.

     [EACCES]		Search permission is denied for a component of the  path
			prefix.

     [EACCES]		The  required  permissions  (for reading and/or writing)
			are denied for the given flags.

     [EACCES]		O_TRUNC is specified and write permission is denied.

     [EACCES]		O_CREAT is specified, the file does not exist,	and  the
			directory  in  which it is to be created does not permit
			writing.

     [EPERM]		O_CREAT is specified, the file does not exist,	and  the
			directory in which it is to be created has its immutable
			flag set, see the chflags(2) manual page for more infor-
			mation.

     [EPERM]		The  named  file has its immutable flag set and the file
			is to be modified.

     [EPERM]		The named file has its append-only flag set, the file is
			to be modified, and O_TRUNC is specified or O_APPEND  is
			not specified.

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

     [EISDIR]		The named file is a directory, and the arguments specify
			it is to be modified.

     [EROFS]		The named file resides on a read-only file  system,  and
			the file is to be modified.

     [EROFS]		O_CREAT  is specified and the named file would reside on
			a read-only file system.

     [EMFILE]		The process has already reached its limit for open  file
			descriptors.

     [ENFILE]		The system file table is full.

     [EMLINK]		O_NOFOLLOW  was  specified  and the target is a symbolic
			link.

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

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

     [EINTR]		The open() operation was interrupted by a signal.

     [EOPNOTSUPP]	O_SHLOCK or O_EXLOCK is  specified  but  the  underlying
			file system does not support locking.

     [EOPNOTSUPP]	The  named file is a special file mounted through a file
			system that does not support access to it (e.g. NFS).

     [EWOULDBLOCK]	O_NONBLOCK and one of O_SHLOCK or O_EXLOCK is  specified
			and the file is locked.

     [ENOSPC]		O_CREAT  is  specified, the file does not exist, and the
			directory in which the entry for the new file  is  being
			placed cannot be extended because there is no space left
			on the file system containing the directory.

     [ENOSPC]		O_CREAT is specified, the file does not exist, and there
			are  no free inodes on the file system on which the file
			is being created.

     [EDQUOT]		O_CREAT is specified, the file does not exist,	and  the
			directory  in  which the entry for the new file is being
			placed cannot be extended because the  user's  quota  of
			disk  blocks on the file system containing the directory
			has been exhausted.

     [EDQUOT]		O_CREAT is specified, the file does not exist,	and  the
			user's	quota  of inodes on the file system on which the
			file is being created has been exhausted.

     [EIO]		An I/O error occurred while making the	directory  entry
			or allocating the inode for O_CREAT.

     [ETXTBSY]		The  file is a pure procedure (shared text) file that is
			being executed and the open() system call requests write
			access.

     [EFAULT]		The path argument points outside the process's allocated
			address space.

     [EEXIST]		O_CREAT and O_EXCL were specified and the file exists.

     [EOPNOTSUPP]	An attempt was made to open a socket (not currently  im-
			plemented).

     [EINVAL]		An attempt was made to open a descriptor with an illegal
			combination of O_RDONLY, O_WRONLY, O_RDWR and O_EXEC.

     [EBADF]		The  path argument does not specify an absolute path and
			the fd argument is neither AT_FDCWD nor a valid file de-
			scriptor open for searching.

     [ENOTDIR]		The path argument is not an absolute path and fd is nei-
			ther AT_FDCWD nor a file descriptor  associated  with  a
			directory.

SEE ALSO
     chmod(2),	 close(2),   dup(2),  fexecve(2),  fhopen(2),  getdtablesize(2),
     getfh(2), lgetfh(2), lseek(2), read(2), umask(2), write(2), fopen(3)

HISTORY
     The open() function appeared in Version 6 AT&T UNIX.  The openat() function
     was introduced in FreeBSD 8.0.

BUGS
     The Open Group Extended API Set 2 specification requires that the test  for
     whether  fd is searchable is based on whether fd is open for searching, not
     whether the underlying directory currently permits searches.   The  present
     implementation  of  the  openat checks the current permissions of directory
     instead.

FreeBSD 8.3			 March 25, 2011 			 OPEN(2)

home | help