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

FreeBSD Manual Pages

  
 
  

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

NAME
     open -- open or create a file for reading or writing

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <fcntl.h>

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

DESCRIPTION
     The file name specified by	path is	opened for reading and/or writing as
     specified by the argument flags and the file descriptor returned to the
     calling process.  The flags are specified by or'ing the values listed be-
     low.  Applications	must specify exactly one of the	first three values
     (file access methods):

	   O_RDONLY	Open for reading only.

	   O_WRONLY	Open for writing only.

	   O_RDWR	Open for reading and writing.

     Any combination of	the following may be used:

	   O_NONBLOCK	Do not block on	open or	for data to become available.

	   O_APPEND	Append to the file on each write.

	   O_CREAT	Create the file	if it does not exist.  The third argu-
			ment of	type mode_t is used to compute the mode	bits
			of the file as described in chmod(2) and modified by
			the process' umask value (see umask(2)).

	   O_TRUNC	Truncate size to 0.

	   O_EXCL	Error if O_CREAT and the file already exists.

	   O_SHLOCK	Atomically obtain a shared lock.

	   O_EXLOCK	Atomically obtain an exclusive lock.

	   O_NOFOLLOW	If last	path element is	a symlink, don't follow	it.
			This option is provided	for compatibility with other
			operating systems, but its security value is question-
			able.

	   O_CLOEXEC	Set the	close(2) on exec(3) flag.

	   O_NOSIGPIPE	Return EPIPE instead of	raising	SIGPIPE.

	   O_DSYNC	If set,	write operations will be performed according
			to synchronized	I/O data integrity completion: each
			write will wait	for the	file data to be	committed to
			stable storage.

	   O_SYNC	If set,	write operations will be performed according
			to synchronized	I/O file integrity completion: each
			write will wait	for both the file data and file	status
			to be committed	to stable storage.

	   O_RSYNC	If set,	read operations	will complete at the same
			level of integrity which is in effect for write	opera-
			tions: if specified together with O_SYNC, each read
			will wait for the file status to be committed to sta-
			ble storage.

			Combining O_RSYNC with O_DSYNC only, or	specifying it
			without	any other synchronized I/O integrity comple-
			tion flag set, has no further effect.

	   O_ALT_IO	Alternate I/O semantics	will be	used for read and
			write operations on the	file descriptor.  Alternate
			semantics are defined by the underlying	layers and
			will not have any alternate effect in most cases.

	   O_NOCTTY	If the file is a terminal device, the opened device is
			not made the controlling terminal for the session.
			This flag has no effect	on NetBSD, since the system
			defaults to the	abovementioned behaviour.  The flag is
			present	only for standards conformance.

	   O_DIRECT	If set on a regular file, data I/O operations will not
			buffer the data	being transferred in the kernel's
			cache, but rather transfer the data directly between
			user memory and	the underlying device driver if	possi-
			ble.  This flag	is advisory; the request may be	per-
			formed in the normal buffered fashion if certain con-
			ditions	are not	met, e.g. if the request is not	suffi-
			ciently	aligned	or if the file is mapped.

			To meet	the alignment requirements for direct I/O, the
			file offset, the length	of the I/O and the address of
			the buffer in memory must all be multiples of
			DEV_BSIZE (512 bytes).	If the I/O request is made us-
			ing an interface that supports scatter/gather via
			struct iovec, each element of the request must meet
			the above alignment constraints.

	   O_DIRECTORY	Fail if	the file is not	a directory.

	   O_ASYNC	Enable the SIGIO signal	to be sent to the process
			group when I/O is possible, e.g., upon availability of
			data to	be read.

     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	lock-
     ing 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, do not wait for the device or	file
     to	be ready or available.	If the open() call would result	in the process
     being blocked for some reason (e.g., waiting for carrier on a dialup
     line), open() returns immediately.	 This flag also	has the	effect of mak-
     ing all subsequent	I/O on the open	file non-blocking.

     When opening a file, a lock with flock(2) semantics can be	obtained by
     setting 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 filesystem supports locking).

     If	open() is successful, the file pointer used to mark the	current	posi-
     tion 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.

     The new descriptor	is set to remain open across execve(2) system calls;
     see close(2) and fcntl(2).

     The system	imposes	a limit	on the number of file descriptors open simul-
     taneously by one process.	Calling	getdtablesize(3) returns the current
     system limit.

RETURN VALUES
     If	successful, open() returns a non-negative integer, termed a file de-
     scriptor.	Otherwise, a value of -1 is returned and errno is set to indi-
     cate the error.

ERRORS
     The named file is opened unless:

     [EACCES]		Search permission is denied for	a component of the
			path prefix, the required permissions (for reading
			and/or writing)	are denied for the given flags,	or
			O_CREAT	is specified, the file does not	exist, and the
			directory in which it is to be created does not	permit
			writing.

     [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 direc-
			tory has been exhausted; or 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.

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

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

     [EFTYPE]		O_NOFOLLOW was specified, but the last path component
			is a symlink.  Note: IEEE Std 1003.1-2008 ("POSIX.1")
			specifies returning [ELOOP] for	this case.

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

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

     [EISDIR]		The named file is a directory, and the arguments spec-
			ify it is to be	opened for writing.

     [ELOOP]		Too many symbolic links	were encountered in translat-
			ing the	pathname.

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

     [ENAMETOOLONG]	A component of a pathname exceeded {NAME_MAX} charac-
			ters, or an entire path	name exceeded {PATH_MAX} char-
			acters.

     [ENFILE]		The system file	table is full.

     [ENOENT]		O_CREAT	is not set and the named file does not exist,
			or a component of the path name	that must exist	does
			not exist.

     [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; or
			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.

     [ENOTDIR]		A component of the path	prefix is not a	directory; or
			O_DIRECTORY is specified and the last path component
			is not a directory.

     [ENXIO]		The named file is a character special or block special
			file, and the device associated	with this special file
			does not exist,	or the named file is a FIFO,
			O_NONBLOCK and O_WRONLY	is set and no process has the
			file open for reading.

     [EOPNOTSUPP]	O_SHLOCK or O_EXLOCK is	specified but the underlying
			filesystem does	not support locking; or	an attempt was
			made to	open a socket (not currently implemented).

     [EPERM]		The file's flags (see chflags(2)) don't	allow the file
			to be opened.

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

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

SEE ALSO
     chmod(2), close(2), dup(2), lseek(2), read(2), umask(2), write(2),
     getdtablesize(3)

STANDARDS
     The open()	function conforms to ISO/IEC 9945-1:1990 ("POSIX.1").  The
     flags values O_DSYNC, O_SYNC and O_RSYNC are extensions defined in	IEEE
     Std 1003.1b-1993 ("POSIX.1").

     The O_SHLOCK and O_EXLOCK flags are non-standard extensions and should
     not be used if portability	is of concern.

HISTORY
     An	open() function	call appeared in Version 2 AT&T	UNIX.

BSD			       January 23, 2012				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS | HISTORY

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

home | help