1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)open.2 8.2 (Berkeley) 11/16/93
|
29.\" $FreeBSD: head/lib/libc/sys/open.2 165903 2007-01-09 00:28:16Z imp $
|
29.\" $FreeBSD: head/lib/libc/sys/open.2 178245 2008-04-16 13:03:12Z kib $ |
30.\"
|
31.Dd January 7, 2007
|
31.Dd April 10, 2008 |
32.Dt OPEN 2 33.Os 34.Sh NAME
|
35.Nm open
36.Nd open or create a file for reading or writing
|
35.Nm open , openat 36.Nd open or create a file for reading, writing or executing |
37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In fcntl.h 41.Ft int 42.Fn open "const char *path" "int flags" "..."
|
43.Ft int 44.Fn openat "int fd" "const char *path" "int flags" "..." |
45.Sh DESCRIPTION 46The file name specified by 47.Fa path 48is opened
|
47for reading and/or writing as specified by the
|
49for either execution or reading and/or writing as specified by the |
50argument 51.Fa flags 52and the file descriptor returned to the calling process. 53The 54.Fa flags 55argument may indicate the file is to be 56created if it does not exist (by specifying the 57.Dv O_CREAT 58flag). 59In this case 60.Fn open
|
59requires a third argument
|
61and 62.Fn openat 63require an additional argument |
64.Fa "mode_t mode" , 65and the file is created with mode 66.Fa mode 67as described in 68.Xr chmod 2 69and modified by the process' umask value (see 70.Xr umask 2 ) . 71.Pp
|
72The 73.Fn openat 74function is equivalent to the 75.Fn open 76function except in the case where the 77.Fa path 78specifies a relative path. 79In this case the file to be opened is determined relative to the directory 80associated with the file descriptor 81.Fa fd 82instead of the current working directory. 83The 84.Fa flag 85parameter and the optional fourth parameter correspond exactly to 86the parameters of 87.Fn open . 88If 89.Fn openat 90is passed the special value 91.Dv AT_FDCWD 92in the 93.Fa fd 94parameter, the current working directory is used 95and the behavior is identical to a call to 96.Fn open . 97.Pp |
98The flags specified are formed by 99.Em or Ns 'ing 100the following values 101.Pp 102.Bd -literal -offset indent -compact 103O_RDONLY open for reading only 104O_WRONLY open for writing only 105O_RDWR open for reading and writing
|
106O_EXEC open for execute only |
107O_NONBLOCK do not block on open 108O_APPEND append on each write 109O_CREAT create file if it does not exist 110O_TRUNC truncate size to 0 111O_EXCL error if create and file exists 112O_SHLOCK atomically obtain a shared lock 113O_EXLOCK atomically obtain an exclusive lock 114O_DIRECT eliminate or reduce cache effects 115O_FSYNC synchronous writes 116O_SYNC synchronous writes 117O_NOFOLLOW do not follow symlinks 118O_NOCTTY don't assign controlling terminal 119.Ed 120.Pp 121Opening a file with 122.Dv O_APPEND 123set causes each write on the file 124to be appended to the end. 125If 126.Dv O_TRUNC 127is specified and the 128file exists, the file is truncated to zero length. 129If 130.Dv O_EXCL 131is set with 132.Dv O_CREAT 133and the file already 134exists, 135.Fn open 136returns an error. 137This may be used to 138implement a simple exclusive access locking mechanism. 139If 140.Dv O_EXCL 141is set and the last component of the pathname is 142a symbolic link, 143.Fn open 144will fail even if the symbolic 145link points to a non-existent name. 146If the 147.Dv O_NONBLOCK 148flag is specified and the 149.Fn open 150system call would result 151in the process being blocked for some reason (e.g., waiting for 152carrier on a dialup line), 153.Fn open 154returns immediately. 155The descriptor remains in non-blocking mode for subsequent operations. 156.Pp 157If 158.Dv O_FSYNC 159is used in the mask, all writes will 160immediately be written to disk, 161the kernel will not cache written data 162and all writes on the descriptor will not return until 163the data to be written completes. 164.Pp 165.Dv O_SYNC 166is a synonym for 167.Dv O_FSYNC 168required by 169.Tn POSIX . 170.Pp 171If 172.Dv O_NOFOLLOW 173is used in the mask and the target file passed to 174.Fn open 175is a symbolic link then the 176.Fn open 177will fail. 178.Pp 179When opening a file, a lock with 180.Xr flock 2 181semantics can be obtained by setting 182.Dv O_SHLOCK 183for a shared lock, or 184.Dv O_EXLOCK 185for an exclusive lock. 186If creating a file with 187.Dv O_CREAT , 188the request for the lock will never fail 189(provided that the underlying file system supports locking). 190.Pp 191.Dv O_DIRECT 192may be used to minimize or eliminate the cache effects of reading and writing. 193The system will attempt to avoid caching the data you read or write. 194If it cannot avoid caching the data, 195it will minimize the impact the data has on the cache. 196Use of this flag can drastically reduce performance if not used with care. 197.Pp 198.Dv O_NOCTTY 199may be used to ensure the OS does not assign this file as the 200controlling terminal when it opens a tty device. 201This is the default on 202.Fx , 203but is present for 204.Tn POSIX 205compatibility. 206The 207.Fn open 208system call will not assign controlling terminals on 209.Fx . 210.Pp 211If successful, 212.Fn open 213returns a non-negative integer, termed a file descriptor.
|
183It returns -1 on failure.
|
214It returns \-1 on failure. |
215The file pointer used to mark the current position within the 216file is set to the beginning of the file. 217.Pp 218When a new file is created it is given the group of the directory 219which contains it. 220.Pp 221The new descriptor is set to remain open across 222.Xr execve 2 223system calls; see 224.Xr close 2 225and 226.Xr fcntl 2 . 227.Pp 228The system imposes a limit on the number of file descriptors 229open simultaneously by one process. 230The 231.Xr getdtablesize 2 232system call returns the current system limit. 233.Sh RETURN VALUES 234If successful, 235.Fn open
|
205returns a non-negative integer, termed a file descriptor.
206It returns -1 on failure, and sets
|
236and 237.Fn openat 238return a non-negative integer, termed a file descriptor. 239They return \-1 on failure, and set |
240.Va errno 241to indicate the error. 242.Sh ERRORS 243The named file is opened unless: 244.Bl -tag -width Er 245.It Bq Er ENOTDIR 246A component of the path prefix is not a directory. 247.It Bq Er ENAMETOOLONG 248A component of a pathname exceeded 255 characters, 249or an entire path name exceeded 1023 characters. 250.It Bq Er ENOENT 251.Dv O_CREAT 252is not set and the named file does not exist. 253.It Bq Er ENOENT 254A component of the path name that must exist does not exist. 255.It Bq Er EACCES 256Search permission is denied for a component of the path prefix. 257.It Bq Er EACCES 258The required permissions (for reading and/or writing) 259are denied for the given flags. 260.It Bq Er EACCES 261.Dv O_TRUNC 262is specified and write permission is denied. 263.It Bq Er EACCES 264.Dv O_CREAT 265is specified, 266the file does not exist, 267and the directory in which it is to be created 268does not permit writing. 269.It Bq Er EPERM 270.Dv O_CREAT 271is specified, the file does not exist, and the directory in which it is to be 272created has its immutable flag set, see the 273.Xr chflags 2 274manual page for more information. 275.It Bq Er EPERM 276.Dv The named file has its immutable flag set and the file is to be modified. 277.It Bq Er EPERM 278.Dv The named file has its append-only flag set, the file is to be modified, and 279.Dv O_TRUNC 280is specified or 281.Dv O_APPEND 282is not specified. 283.It Bq Er ELOOP 284Too many symbolic links were encountered in translating the pathname. 285.It Bq Er EISDIR 286The named file is a directory, and the arguments specify 287it is to be modified. 288.It Bq Er EROFS 289The named file resides on a read-only file system, 290and the file is to be modified. 291.It Bq Er EROFS 292.Dv O_CREAT 293is specified and the named file would reside on a read-only file system. 294.It Bq Er EMFILE 295The process has already reached its limit for open file descriptors. 296.It Bq Er ENFILE 297The system file table is full. 298.It Bq Er EMLINK 299.Dv O_NOFOLLOW 300was specified and the target is a symbolic link. 301.It Bq Er ENXIO 302The named file is a character special or block 303special file, and the device associated with this special file 304does not exist. 305.It Bq Er ENXIO 306.Dv O_NONBLOCK 307is set, the named file is a fifo, 308.Dv O_WRONLY 309is set, and no process has the file open for reading. 310.It Bq Er EINTR 311The 312.Fn open 313operation was interrupted by a signal. 314.It Bq Er EOPNOTSUPP 315.Dv O_SHLOCK 316or 317.Dv O_EXLOCK 318is specified but the underlying file system does not support locking. 319.It Bq Er EOPNOTSUPP 320The named file is a special file mounted through a file system that 321does not support access to it (e.g.\& NFS). 322.It Bq Er EWOULDBLOCK 323.Dv O_NONBLOCK 324and one of 325.Dv O_SHLOCK 326or 327.Dv O_EXLOCK 328is specified and the file is locked. 329.It Bq Er ENOSPC 330.Dv O_CREAT 331is specified, 332the file does not exist, 333and the directory in which the entry for the new file is being placed 334cannot be extended because there is no space left on the file 335system containing the directory. 336.It Bq Er ENOSPC 337.Dv O_CREAT 338is specified, 339the file does not exist, 340and there are no free inodes on the file system on which the 341file is being created. 342.It Bq Er EDQUOT 343.Dv O_CREAT 344is specified, 345the file does not exist, 346and the directory in which the entry for the new file 347is being placed cannot be extended because the 348user's quota of disk blocks on the file system 349containing the directory has been exhausted. 350.It Bq Er EDQUOT 351.Dv O_CREAT 352is specified, 353the file does not exist, 354and the user's quota of inodes on the file system on 355which the file is being created has been exhausted. 356.It Bq Er EIO 357An I/O error occurred while making the directory entry or 358allocating the inode for 359.Dv O_CREAT . 360.It Bq Er ETXTBSY 361The file is a pure procedure (shared text) file that is being 362executed and the 363.Fn open 364system call requests write access. 365.It Bq Er EFAULT 366The 367.Fa path 368argument 369points outside the process's allocated address space. 370.It Bq Er EEXIST 371.Dv O_CREAT 372and 373.Dv O_EXCL 374were specified and the file exists. 375.It Bq Er EOPNOTSUPP 376An attempt was made to open a socket (not currently implemented). 377.It Bq Er EINVAL 378An attempt was made to open a descriptor with an illegal combination 379of 380.Dv O_RDONLY , 381.Dv O_WRONLY ,
|
382.Dv O_RDWR |
383and
|
350.Dv O_RDWR .
|
384.Dv O_EXEC. 385.It Bq Eq EBADF 386The 387.Fa path 388argument does not specify an absolute path and the 389.Fa fd 390argument is 391neither 392.Dv AT_FDCWD 393nor a valid file descriptor open for searching. 394.It Bq Eq ENOTDIR 395The 396.Fa path 397argument is not an absolute path and 398.Fa fd 399is neither 400.Dv AT_FDCWD 401nor a file descriptor associated with a directory. |
402.El 403.Sh SEE ALSO 404.Xr chmod 2 , 405.Xr close 2 , 406.Xr dup 2 ,
|
407.Xr fexecve 2 , |
408.Xr fhopen 2 , 409.Xr getdtablesize 2 , 410.Xr getfh 2 , 411.Xr lgetfh 2 , 412.Xr lseek 2 , 413.Xr read 2 , 414.Xr umask 2 , 415.Xr write 2 , 416.Xr fopen 3 417.Sh HISTORY 418The 419.Fn open 420function appeared in 421.At v6 .
|
422The 423.Fn openat 424function was introduced in 425.Fx 8.0 . 426.Sh BUGS 427The Open Group Extended API Set 2 specification requires that the test 428for whether 429.Fa fd 430is searchable is based on whether 431.Fa fd 432is open for searching, not whether the underlying directory currently 433permits searches. 434The present implementation of the 435.Fa openat 436checks the current permissions of directory instead. |
|