open man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

OPEN(P)			   POSIX Programmer's Manual		       OPEN(P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       open - open a file

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

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

DESCRIPTION
       The open() function shall establish the connection between a file and a
       file  descriptor.  It shall create an open file description that refers
       to a file and a file descriptor that refers to that open file  descrip‐
       tion.  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 shall return 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
       shall not share it with any other process in the system. The FD_CLOEXEC
       file descriptor flag associated with the new file descriptor  shall  be
       cleared.

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

       The file status flags and file access modes of the open	file  descrip‐
       tion shall be 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 shall 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  shall be 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 shall be created; the
	      user ID of the file shall be set to the effective user ID of the
	      process;	the  group ID of the file shall be set to the group ID
	      of the file's parent directory or to the effective group	ID  of
	      the  process;  and the access permission bits (see <sys/stat.h>)
	      of the file mode shall be set to the value of the third argument
	      taken  as type mode_t modified as follows: a bitwise AND is per‐
	      formed on the file-mode bits and the corresponding bits  in  the
	      complement  of  the  process' file mode creation mask. Thus, all
	      bits in the file mode whose corresponding bit in the  file  mode
	      creation	mask is set are cleared. When bits other than the file
	      permission bits are set, the effect is  unspecified.  The	 third
	      argument	does  not affect whether the file is open for reading,
	      writing, or for both. Implementations shall  provide  a  way  to
	      initialize  the  file's  group  ID to the group ID of the parent
	      directory.  Implementations may, but need not, provide an imple‐
	      mentation-defined	 way  to initialize the file's group ID to the
	      effective group ID of the calling process.

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

       O_EXCL If  O_CREAT  and	O_EXCL	are set, open() shall fail if the file
	      exists. The check for the existence of the file and the creation
	      of the file if it does not exist shall be atomic with respect to
	      other threads executing open() naming the same filename  in  the
	      same  directory  with  O_EXCL  and  O_CREAT  set.	 If O_EXCL and
	      O_CREAT are set, and path names a symbolic  link,	 open()	 shall
	      fail  and	 set  errno to [EEXIST], regardless of the contents of
	      the symbolic link. If O_EXCL is set and O_CREAT is not set,  the
	      result is undefined.

       O_NOCTTY
	      If  set  and path identifies a terminal device, open() shall not
	      cause the terminal device to become the controlling terminal for
	      the process.

       O_NONBLOCK
	      When opening a FIFO with O_RDONLY or O_WRONLY set:

	       * If O_NONBLOCK is set, an open() for reading-only shall return
		 without delay. An open() for  writing-only  shall  return  an
		 error if no process currently has the file open for reading.

	       * If  O_NONBLOCK	 is  clear,  an	 open() for reading-only shall
		 block the calling thread until a thread opens	the  file  for
		 writing.  An  open() for writing-only shall block the calling
		 thread until a thread opens the file for reading.

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

	       * If  O_NONBLOCK is set, the open() function shall return with‐
		 out blocking for the device to be ready or available.	Subse‐
		 quent behavior of the device is device-specific.

	       * If  O_NONBLOCK	 is clear, the open() function shall block the
		 calling thread until the device is ready or available	before
		 returning.

       Otherwise, the behavior of O_NONBLOCK is unspecified.

       O_RSYNC
	      Read I/O operations on the file descriptor shall 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 shall complete as  defined  by
	      synchronized  I/O	 data integrity completion. If both O_SYNC and
	      O_RSYNC are set  in  flags,  all	I/O  operations	 on  the  file
	      descriptor  shall	 complete  as defined by synchronized I/O file
	      integrity completion.

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

       O_TRUNC
	      If  the  file exists and is a regular file, and the file is suc‐
	      cessfully opened O_RDWR or O_WRONLY, its length shall  be	 trun‐
	      cated  to 0, and the mode and owner shall be unchanged. It shall
	      have no effect on FIFO special files or terminal	device	files.
	      Its  effect  on  other file types is implementation-defined. 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()	 shall mark 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() shall mark for  update  the  st_ctime	 and  st_mtime
       fields of the file.

       If  both the O_SYNC and O_DSYNC flags are set, the effect is as if only
       the O_SYNC flag was set.

       If path refers to a STREAMS file, oflag may be constructed from	O_NON‐
       BLOCK  OR'ed with either O_RDONLY, O_WRONLY, or O_RDWR. Other flag val‐
       ues are not applicable to STREAMS devices and shall have no  effect  on
       them. The value O_NONBLOCK affects the operation of STREAMS drivers and
       certain functions applied to file descriptors associated	 with  STREAMS
       files. For STREAMS drivers, the implementation of O_NONBLOCK is device-
       specific.

       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. Conforming applications shall call  unlockpt()  before  opening
       the slave side.

       The  largest  value  that  can be represented correctly in an object of
       type off_t shall be established as the offset maximum in the open  file
       description.

RETURN VALUE
       Upon successful completion, the function shall open the file and return
       a non-negative integer representing the	lowest	numbered  unused  file
       descriptor.  Otherwise,	-1 shall be returned and errno set to indicate
       the error. No files shall  be  created  or  modified  if	 the  function
       returns -1.

ERRORS
       The open() function shall fail 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.

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

       EINTR  A signal was caught during open().

       EINVAL The  implementation  does	 not support synchronized I/O for this
	      file.

       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  A loop exists in symbolic links encountered during resolution of
	      the path argument.

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

       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.

       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.

       EOVERFLOW
	      The named file is a regular file and the size of the file cannot
	      be represented correctly in an object of type off_t.

       EROFS  The named file resides on a read-only  file  system  and	either
	      O_WRONLY,	 O_RDWR,  O_CREAT  (if	the  file  does not exist), 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-terminal
	      device that is locked.

       EINVAL The value of the oflag argument is not valid.

       ELOOP  More  than  {SYMLOOP_MAX} symbolic links were encountered during
	      resolution of the path argument.

       ENAMETOOLONG
	      As a result of encountering a symbolic link in resolution of the
	      path  argument,  the  length  of the substituted pathname string
	      exceeded {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.

       The following sections are informative.

EXAMPLES
   Opening a File for Writing by the Owner
       The following example opens the file /tmp/file, either by  creating  it
       (if it does not already exist), or by truncating its length to 0 (if it
       does exist). In the former case, if the call creates a  new  file,  the
       access  permission  bits in the file mode of the file are set to permit
       reading and writing by the owner, and to permit reading only  by	 group
       members and others.

       If the call to open() is successful, the file is opened for writing.

	      #include <fcntl.h>
	      ...
	      int fd;
	      mode_t mode = S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH;
	      char *filename = "/tmp/file";
	      ...
	      fd = open(filename, O_WRONLY | O_CREAT | O_TRUNC, mode);
	      ...

   Opening a File Using an Existence Check
       The  following  example	uses  the open() function to try to create the
       LOCKFILE file and open it for writing. Since the open() function speci‐
       fies  the  O_EXCL  flag,	 the call fails if the file already exists. In
       that case, the program assumes that someone else is updating the	 pass‐
       word file and exits.

	      #include <fcntl.h>
	      #include <stdio.h>
	      #include <stdlib.h>

	      #define LOCKFILE "/etc/ptmp"
	      ...
	      int pfd; /* Integer for file descriptor returned by open() call. */
	      ...
	      if ((pfd = open(LOCKFILE, O_WRONLY | O_CREAT | O_EXCL,
		  S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
	      {
		  fprintf(stderr, "Cannot open /etc/ptmp. Try again later.\n");
		  exit(1);
	      }
	      ...

   Opening a File for Writing
       The following example opens a file for writing, creating the file if it
       does not already exist. If the file does exist,	the  system  truncates
       the file to zero bytes.

	      #include <fcntl.h>
	      #include <stdio.h>
	      #include <stdlib.h>

	      #define LOCKFILE "/etc/ptmp"
	      ...
	      int pfd;
	      char filename[PATH_MAX+1];
	      ...
	      if ((pfd = open(filename, O_WRONLY | O_CREAT | O_TRUNC,
		  S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1)
	      {
		  perror("Cannot open output file\n"); exit(1);
	      }
	      ...

APPLICATION USAGE
       None.

RATIONALE
       Except  as  specified in this volume of IEEE Std 1003.1-2001, the flags
       allowed in oflag are not mutually-exclusive and any number of them  may
       be used simultaneously.

       Some  implementations  permit  opening  FIFOs  with O_RDWR. Since FIFOs
       could be implemented in other ways, and since two file descriptors  can
       be used to the same effect, this possibility is left as undefined.

       See getgroups() about the group of a newly created file.

       The  use of open() to create a regular file is preferable to the use of
       creat(), because the latter is redundant and included only for histori‐
       cal reasons.

       The  use	 of the O_TRUNC flag on FIFOs and directories (pipes cannot be
       open()-ed) must be permissible without  unexpected  side	 effects  (for
       example,	 creat()  on a FIFO must not remove data). Since terminal spe‐
       cial files might have type-ahead data stored  in	 the  buffer,  O_TRUNC
       should  not  affect  their content, particularly if a program that nor‐
       mally opens a regular file should open the current controlling terminal
       instead.	 Other	file  types, particularly implementation-defined ones,
       are left implementation-defined.

       IEEE Std 1003.1-2001 permits [EACCES] to	 be  returned  for  conditions
       other than those explicitly listed.

       The O_NOCTTY flag was added to allow applications to avoid unintention‐
       ally acquiring a controlling terminal as a side	effect	of  opening  a
       terminal file. This volume of IEEE Std 1003.1-2001 does not specify how
       a controlling terminal is acquired, but it allows an implementation  to
       provide this on open() if the O_NOCTTY flag is not set and other condi‐
       tions specified in the Base Definitions volume of IEEE Std 1003.1-2001,
       Chapter 11, General Terminal Interface are met. The O_NOCTTY flag is an
       effective no-op if the file being opened is not a terminal device.

       In historical implementations the value of O_RDONLY is zero. Because of
       that, it is not possible to detect the presence of O_RDONLY and another
       option. Future implementations should encode O_RDONLY and  O_WRONLY  as
       bit flags so that:

	      O_RDONLY | O_WRONLY == O_RDWR

       In general, the open() function follows the symbolic link if path names
       a symbolic link. However, the open() function, when called with O_CREAT
       and O_EXCL, is required to fail with [EEXIST] if path names an existing
       symbolic link, even if the symbolic link refers to a nonexistent	 file.
       This  behavior is required so that privileged applications can create a
       new file in a known location without the possibility  that  a  symbolic
       link might cause the file to be created in a different location.

       For  example,  a	 privileged application that must create a file with a
       predictable name in a user-writable directory, such as the user's  home
       directory,  could  be  compromised  if the user creates a symbolic link
       with that name that refers to a nonexistent file in a system directory.
       If  the	user can influence the contents of a file, the user could com‐
       promise the system by creating a new system configuration or spool file
       that  would  then be interpreted by the system. The test for a symbolic
       link which refers to a nonexisting file must be atomic  with  the  cre‐
       ation of a new file.

       The POSIX.1-1990 standard required that the group ID of a newly created
       file be set to the group ID of its parent directory or to the effective
       group  ID of the creating process. FIPS 151-2 required that implementa‐
       tions provide a way to have the group ID be set to the group ID of  the
       containing  directory,  but  did not prohibit implementations also sup‐
       porting a way to set the group ID to the effective group ID of the cre‐
       ating process. Conforming applications should not assume which group ID
       will be used. If it matters, an application can use chown() to set  the
       group  ID after the file is created, or determine under what conditions
       the implementation will set the desired group ID.

FUTURE DIRECTIONS
       None.

SEE ALSO
       chmod() , close() , creat() , dup() , fcntl()  ,	 lseek()  ,  read()  ,
       umask()	,  unlockpt()  ,  write()  ,  the  Base	 Definitions volume of
       IEEE Std 1003.1-2001, <fcntl.h>, <sys/stat.h>, <sys/types.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the	referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			       OPEN(P)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net