| open.2 (165903) | open.2 (178245) |
|---|---|
| 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. --- 12 unchanged lines hidden (view full) --- 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 | 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. --- 12 unchanged lines hidden (view full) --- 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.\" | 30.\" |
| 31.Dd January 7, 2007 | 31.Dd April 10, 2008 |
| 32.Dt OPEN 2 33.Os 34.Sh NAME | 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" "..." | 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" "..." |
|
| 43.Sh DESCRIPTION 44The file name specified by 45.Fa path 46is opened | 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 |
| 48argument 49.Fa flags 50and the file descriptor returned to the calling process. 51The 52.Fa flags 53argument may indicate the file is to be 54created if it does not exist (by specifying the 55.Dv O_CREAT 56flag). 57In this case 58.Fn open | 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 |
| 60.Fa "mode_t mode" , 61and the file is created with mode 62.Fa mode 63as described in 64.Xr chmod 2 65and modified by the process' umask value (see 66.Xr umask 2 ) . 67.Pp | 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 |
|
| 68The flags specified are formed by 69.Em or Ns 'ing 70the following values 71.Pp 72.Bd -literal -offset indent -compact 73O_RDONLY open for reading only 74O_WRONLY open for writing only 75O_RDWR open for reading and writing | 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 |
|
| 76O_NONBLOCK do not block on open 77O_APPEND append on each write 78O_CREAT create file if it does not exist 79O_TRUNC truncate size to 0 80O_EXCL error if create and file exists 81O_SHLOCK atomically obtain a shared lock 82O_EXLOCK atomically obtain an exclusive lock 83O_DIRECT eliminate or reduce cache effects --- 91 unchanged lines hidden (view full) --- 175The 176.Fn open 177system call will not assign controlling terminals on 178.Fx . 179.Pp 180If successful, 181.Fn open 182returns a non-negative integer, termed a file descriptor. | 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 --- 91 unchanged lines hidden (view full) --- 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. |
| 184The file pointer used to mark the current position within the 185file is set to the beginning of the file. 186.Pp 187When a new file is created it is given the group of the directory 188which contains it. 189.Pp 190The new descriptor is set to remain open across 191.Xr execve 2 --- 5 unchanged lines hidden (view full) --- 197The system imposes a limit on the number of file descriptors 198open simultaneously by one process. 199The 200.Xr getdtablesize 2 201system call returns the current system limit. 202.Sh RETURN VALUES 203If successful, 204.Fn open | 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 --- 5 unchanged lines hidden (view full) --- 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 |
| 207.Va errno 208to indicate the error. 209.Sh ERRORS 210The named file is opened unless: 211.Bl -tag -width Er 212.It Bq Er ENOTDIR 213A component of the path prefix is not a directory. 214.It Bq Er ENAMETOOLONG --- 126 unchanged lines hidden (view full) --- 341were specified and the file exists. 342.It Bq Er EOPNOTSUPP 343An attempt was made to open a socket (not currently implemented). 344.It Bq Er EINVAL 345An attempt was made to open a descriptor with an illegal combination 346of 347.Dv O_RDONLY , 348.Dv O_WRONLY , | 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 --- 126 unchanged lines hidden (view full) --- 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 |
|
| 349and | 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. |
| 351.El 352.Sh SEE ALSO 353.Xr chmod 2 , 354.Xr close 2 , 355.Xr dup 2 , | 402.El 403.Sh SEE ALSO 404.Xr chmod 2 , 405.Xr close 2 , 406.Xr dup 2 , |
| 407.Xr fexecve 2 , |
|
| 356.Xr fhopen 2 , 357.Xr getdtablesize 2 , 358.Xr getfh 2 , 359.Xr lgetfh 2 , 360.Xr lseek 2 , 361.Xr read 2 , 362.Xr umask 2 , 363.Xr write 2 , 364.Xr fopen 3 365.Sh HISTORY 366The 367.Fn open 368function appeared in 369.At v6 . | 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. |
|