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

FreeBSD Manual Pages

  
 
  

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

NAME
       open() -	open file for reading or writing

SYNOPSIS
   Remarks
       The ANSI	C "" construct specifies a variable length argument list whose
       optional	member is given	in the associated comment

DESCRIPTION
       The system call opens a file descriptor for the named file and sets the
       file status flags according to the value	of oflag.

       The path	argument points	to a path name naming a	file, and must not ex-
       ceed bytes in length.

       The oflag argument is a value that is the bitwise inclusive OR of flags
       listed  in  "Read-Write	Flags,"	"General Flags," and "Synchronized I/O
       Flags" below.

       The optional mode argument is only effective when the  flag  is	speci-
       fied.

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

       The new file descriptor is set to remain	open across system calls.  See
       fcntl(2).

   Read-Write Flags
       Exactly	one  of	 the  or  flags	must be	used in	composing the value of
       oflag.  If none or more than one	is used, the behavior is undefined.

	      Open for reading only.

	      Open for writing only.

	      Open for reading and writing.

   General Flags
       Several of the flags listed below can be	changed	with the  system  call
       while the file is open.	See fcntl(2) and fcntl(5) for details.

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

	      If the file exists, this flag has	no effect, except as noted un-
	      der
			     below.   Otherwise,  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 effective
			     group ID of the process if	the  set-group-ID  bit
			     of	 the  parent  directory	 is not	set, or	to the
			     group ID of the  parent  directory	 if  the  set-
			     group-ID bit of the parent	directory is set.

			     The  file	access permission bits of the new file
			     mode are set to the value of  mode,  modified  as
			     follows (see creat(2)):

			     o	For  each  bit	set  in	the file mode creation
				mask of	the process, the corresponding bit  in
				the new	file mode is cleared (see umask(2)).

			     o	The  "save  text image after execution"	bit of
				the new	file mode is cleared.  See chmod(2).

			     o	On HFS file systems with access	control	lists,
				three base ACL entries are created correspond-
				ing  to	 the  file  access  permissions	  (see
				acl(5)).

			     o	On  JFS	 file systems that support access con-
				trol lists, optional ACL entries  are  created
				corresponding  to  the	parent directory's de-
				fault ACL entries (see aclv(5)).

	      If	     and are set and the file exists, fails.

	      This is a	non-standard flag which	may be used by
			     32-bit applications to access files larger	than 2
			     GB.  See creat64(2).

	      This flag	might affect subsequent	reads and writes.
			     See read(2) and write(2).

			     When opening a FIFO with or set:

		     If	is set:

		     A read-only returns without delay.

		     A write-only returns an error if no process currently has
		     the file open for reading.

		     If	is clear:

		     A read-only does not return until	a  process  opens  the
		     file for writing.

		     A	write-only  does  not return until a process opens the
		     file for reading.

			     When opening a file associated with a  communica-
			     tion line:

		     If	is set:

		     The returns without waiting for carrier.

		     If	is clear:

		     The does not return until carrier is present.

	      If set, and    path identifies a terminal	device,	does not cause
			     the terminal to become the	 controlling  terminal
			     for the process.

	      Same effect as for  open(2),  but	 slightly  different effect in
			     read(2) and write(2).  If both and	are specified,
			     takes precedence.

	      If the file exists, its length is	truncated to 0
			     and the mode and owner are	unchanged.

   Synchronized	I/O Flags
       Together, the and flags constitute support for Synchronized I/O.	 These
       flags are ignored for files other than ordinary files and block special
       files  on  those	 systems that permit I/O to block special devices (see
       pathconf(2)).  If both the and flags are	set, the effect	is as if  only
       the  flag was set.  The flag is ignored if it is	not set	along with the
       or flag.

	      If a file	is opened with
		     or	that flag is set with the option  of  writes  to  that
		     file by the process block until the data specified	in the
		     write request and all file	 attributes  required  to  re-
		     trieve the	data are written to the	disk.  File attributes
		     that are not necessary for	data retrieval	(access	 time,
		     modification  time, status	change time) are not necessar-
		     ily written to the	disk prior to returning	to the calling
		     process.

	      Identical	to
		     with the addition that all	file attributes	changed	by the
		     write  operation  (including  access  time,  modification
		     time,  and	 status	 change	 time) are also	written	to the
		     disk prior	to returning to	the calling process.

	      Identical	to
		     for file system writes.

		     For file system reads, the	calling	process	 blocks	 until
		     the  data	being read and all file	attributes required to
		     retrieve the data are the same as their  image  on	 disk.
		     Writes  pending on	the data to be read are	executed prior
		     to	returning to the calling process.

	      Identical	to
		     for file system writes.

		     Identical to for file system  reads,  with	 the  addition
		     that  all	file  attributes changed by the	read operation
		     (including	access time,  modification  time,  and	status
		     change time) too are the same as their image on disk.

RETURN VALUE
       returns the following values:

	      Successful completion.
		     n is a file descriptor for	the opened file.
	      Failure.
		     is	set to indicate	the error.

ERRORS
       If fails, is set	to one of the following	values.

	      [EACCES]	     oflag permission is denied	for the	named file.

	      [EACCES]	     A component of the	path prefix denies search per-
			     mission.

	      [EACCES]	     The file does not	exist  and  the	 directory  in
			     which  the	 file is to be created does not	permit
			     writing.

	      [EACCES]	     is	specified and write permission is denied.

	      [EAGAIN]	     The file  exists,	enforcement  mode  file/record
			     locking  is  set  (see  chmod(2)),	there are out-
			     standing record locks on the  file	 with  the  or
			     system calls, and is set.

	      [EDQUOT]	     User's  disk  quota block or inode	limit has been
			     reached for this file system.

	      [EEXIST]	     and are set and the named file exists.

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

	      [EINTR]	     A	signal	was caught during the system call, and
			     the system	call was not restarted (see  signal(5)
			     and sigvector(2)).

	      [EINVAL]	     oflag specifies both and

	      [EISDIR]	     The  named	file is	a directory and	oflag is write
			     or	read/write.

	      [ELOOP]	     Too many symbolic links are encountered in	trans-
			     lating the	path name.

	      [EMFILE]	     The  maximum  number  of file descriptors allowed
			     are currently open.

	      [ENAMETOOLONG] The length	of the	specified  path	 name  exceeds
			     bytes,  or	 the length of a component of the path
			     name exceeds bytes	while is in effect.

	      [ENFILE]	     The system	file table is full.

	      [ENODEV]	     The named file is a character  special  or	 block
			     special file, and the driver associated with this
			     special file has not  been	 configured  into  the
			     kernel  or	 the  DLKM driver associated with this
			     special file failed to load.

	      [ENOENT]	     The named file does not exist (for	example,  path
			     is	null or	a component of path does not exist, or
			     the file itself does not exist and	is not set).

	      [ENOTDIR]	     A component of the	path prefix is	not  a	direc-
			     tory.

	      [ENXIO]	     is	 set, the named	file is	a FIFO,	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.

	      [ENOSPC]	     is	specified, the file does  not  already	exist,
			     and  the  directory  that	would contain the file
			     cannot be extended.

	      [EOVERFLOW]    The named file is a regular file and the size  of
			     the  file	cannot	be represented correctly in an
			     object of size

	      [EROFS]	     The named file resides on a read-only file	system
			     and oflag is write	or read/write.

	      [ETXTBSY]	     The file is open for execution and	oflag is write
			     or	read/write.  Normal executable files are  only
			     open  for a short time when they start execution.
			     Other executable file types can be	kept open  for
			     a	long  time, or indefinitely under some circum-
			     stances.

EXAMPLES
       The following call to opens file	for reading only and  returns  a  file
       descriptor for For an example of	reading	from file see the read(2) man-
       ual entry.

       The following call to opens file	for writing and	 returns  a  file  de-
       scriptor	 for  For  an  example of preallocating	disk space for see the
       prealloc(2) manual entry.   For	an  example  of	 writing  to  see  the
       write(2)	manual entry.

       The  following  call opens file for synchronized	I/O file integrity for
       reads and writes.

AUTHOR
       was developed by	HP, AT&T, and the University of	California, Berkeley.

SEE ALSO
       acl(2),	chmod(2),  close(2),  creat(2),	 dup(2),  fcntl(2),  lockf(2),
       lseek(2),   creat64(2),	 pathconf(2),  read(2),	 select(2),  umask(2),
       write(2),   setacl(2),	acl(5),	   aclv(5),    fcntl(5),    signal(5),
       thread_safety(5), unistd(5).

STANDARDS CONFORMANCE
								       open(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLES | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

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

home | help