man/man2/open.2

   1 .\" Copyright (c) 1980 Regents of the University of California.
   2 .\" All rights reserved.  The Berkeley software License Agreement
   3 .\" specifies the terms and conditions for redistribution.
   4 .\"
   5 .\"     @(#)open.2      6.4 (Berkeley) 5/14/86
   6 .\"
   7 .TH OPEN 2 "May 14, 1986"
   8 .UC 4
   9 .SH NAME
  10 open \- open a file for reading or writing, or create a new file
  11 .SH SYNOPSIS
  12 .nf
  13 .ft B
  14 #include <sys/types.h>
  15 #include <fcntl.h>
  16
  17 int open(const char *\fIpath\fP, int \fIflags\fP \fR[\fP, mode_t \fImode\fP\fR]\fP)
  18 .ft R
  19 .fi
  20 .SH DESCRIPTION
  21 .B Open
  22 opens the file
  23 .I path
  24 for reading and/or writing, as specified by the
  25 .I flags
  26 argument and returns a descriptor for that file.
  27 The
  28 .I flags
  29 argument may indicate the file is to be
  30 created if it does not already exist (by specifying the
  31 O_CREAT flag), in which case the file is created with mode
  32 .I mode
  33 as described in
  34 .BR chmod (2)
  35 and modified by the process' umask value (see
  36 .BR umask (2)).
  37 .PP
  38 .I Path
  39 is the address of a string of ASCII characters representing
  40 a path name, terminated by a null character.
  41 The flags specified are formed by
  42 .IR or 'ing
  43 the following values
  44 .PP
  45 .RS
  46 .ta +12n
  47 .nf
  48 O_RDONLY        open for reading only
  49 O_WRONLY        open for writing only
  50 O_RDWR  open for reading and writing
  51 O_NONBLOCK      do not block on open
  52 O_APPEND        append on each write
  53 O_CREAT create file if it does not exist
  54 O_TRUNC truncate size to 0
  55 O_EXCL  error if create and file exists
  56 .fi
  57 .DT
  58 .RE
  59 .PP
  60 Opening a file with O_APPEND set causes each write on the file
  61 to be appended to the end.  If O_TRUNC is specified and the
  62 file exists, the file is truncated to zero length.
  63 If O_EXCL is set with O_CREAT, then if the file already
  64 exists, the open returns an error.  This can be used to
  65 implement a simple exclusive access locking mechanism.
  66 If O_EXCL is set and the last component of the pathname is
  67 a symbolic link, the open will fail even if the symbolic
  68 link points to a non-existent name.
  69 If the O_NONBLOCK flag is specified and the open call would result
  70 in the process being blocked for some reason, the open returns immediately.
  71 .PP
  72 Upon successful completion a non-negative integer termed a
  73 file descriptor is returned.
  74 The file pointer used to mark the current position within the
  75 file is set to the beginning of the file.
  76 .PP
  77 The new descriptor is set to remain open across
  78 .BR execve
  79 system calls; see
  80 .BR close (2).
  81 .PP
  82 The system imposes a limit on the number of descriptors
  83 open simultaneously by one process.
  84 .SH "ERRORS
  85 The named file is opened unless one or more of the
  86 following are true:
  87 .TP 15
  88 [ENOTDIR]
  89 A component of the path prefix is not a directory.
  90 .TP 15
  91 [ENAMETOOLONG]
  92 The path name exceeds PATH_MAX characters.
  93 .TP 15
  94 [ENOENT]
  95 O_CREAT is not set and the named file does not exist.
  96 .TP 15
  97 [ENOENT]
  98 A component of the path name that must exist does not exist.
  99 .TP 15
 100 [EACCES]
 101 Search permission is denied for a component of the path prefix.
 102 .TP 15
 103 [EACCES]
 104 The required permissions (for reading and/or writing)
 105 are denied for the named file.
 106 .TP 15
 107 [EACCES]
 108 O_CREAT is specified,
 109 the file does not exist,
 110 and the directory in which it is to be created
 111 does not permit writing.
 112 .TP 15
 113 [EACCES]
 114 A device to be opened for writing is physically write protected.
 115 .TP 15
 116 [ELOOP]
 117 Too many symbolic links were encountered in translating the pathname.
 118 (Minix-vmd)
 119 .TP 15
 120 [EISDIR]
 121 The named file is a directory, and the arguments specify
 122 it is to be opened for writing.
 123 .TP 15
 124 [EROFS]
 125 The named file resides on a read-only file system,
 126 and the file is to be modified.
 127 .TP 15
 128 [EMFILE]
 129 The system limit for open file descriptors per process has already been reached.
 130 .TP 15
 131 [ENFILE]
 132 The system file table is full.
 133 .TP 15
 134 [ENXIO]
 135 The named file is a character special or block
 136 special file, and the device associated with this special file
 137 does not exist.
 138 .TP 15
 139 [ENOSPC]
 140 O_CREAT is specified,
 141 the file does not exist,
 142 and the directory in which the entry for the new file is being placed
 143 cannot be extended because there is no space left on the file
 144 system containing the directory.
 145 .TP 15
 146 [ENOSPC]
 147 O_CREAT is specified,
 148 the file does not exist,
 149 and there are no free inodes on the file system on which the
 150 file is being created.
 151 .ig
 152 .TP 15
 153 [EDQUOT]
 154 O_CREAT is specified,
 155 the file does not exist,
 156 and the directory in which the entry for the new fie
 157 is being placed cannot be extended because the
 158 user's quota of disk blocks on the file system
 159 containing the directory has been exhausted.
 160 .TP 15
 161 [EDQUOT]
 162 O_CREAT is specified,
 163 the file does not exist,
 164 and the user's quota of inodes on the file system on
 165 which the file is being created has been exhausted.
 166 ..
 167 .TP 15
 168 [EIO]
 169 An I/O error occurred while making the directory entry or
 170 allocating the inode for O_CREAT.
 171 .TP 15
 172 [EFAULT]
 173 .I Path
 174 points outside the process's allocated address space.
 175 .TP 15
 176 [EEXIST]
 177 O_CREAT and O_EXCL were specified and the file exists or
 178 .I
 179 path
 180 names a symbolic link (regardless of contents of the link).
 181 .SH "SEE ALSO"
 182 .BR chmod (2),
 183 .BR close (2),
 184 .BR dup (2),
 185 .BR fcntl (2),
 186 .BR lseek (2),
 187 .BR read (2),
 188 .BR write (2),
 189 .BR umask (2).