open.3 (3964B)
1 .TH OPEN 3 2 .SH NAME 3 open, create, close \- open a file for reading or writing, create file 4 .SH SYNOPSIS 5 .B #include <u.h> 6 .br 7 .B #include <libc.h> 8 .PP 9 .B 10 int open(char *file, int omode) 11 .PP 12 .B 13 int create(char *file, int omode, ulong perm) 14 .PP 15 .B 16 int close(int fd) 17 .SH DESCRIPTION 18 .I Open 19 opens the 20 .I file 21 for I/O and returns an associated file descriptor. 22 .I Omode 23 is one of 24 .BR OREAD , 25 .BR OWRITE , 26 .BR ORDWR , 27 or 28 .BR OEXEC , 29 asking for permission to read, write, read and write, or execute, respectively. 30 In addition, there are three values that can be ORed with the 31 .IR omode : 32 .B OTRUNC 33 says to truncate the file 34 to zero length before opening it; 35 .B OCEXEC 36 says to close the file when an 37 .MR exec (3) 38 or 39 .I execl 40 system call is made; 41 .B ORCLOSE 42 says to remove the file when it is closed (by everyone who has a copy of the file descriptor); 43 and 44 .B OAPPEND 45 says to open the file in append-only mode, so that writes 46 are always appended to the end of the file. 47 .I Open 48 fails if the file does not exist or the user does not have 49 permission to open it for the requested purpose 50 (see 51 .MR stat (3) 52 for a description of permissions). 53 The user must have write permission on the 54 .I file 55 if the 56 .B OTRUNC 57 bit is set. 58 For the 59 .I open 60 system call 61 (unlike the implicit 62 .I open 63 in 64 .MR exec (3) ), 65 .B OEXEC 66 is actually identical to 67 .BR OREAD . 68 .PP 69 .I Create 70 creates a new 71 .I file 72 or prepares to rewrite an existing 73 .IR file , 74 opens it according to 75 .I omode 76 (as described for 77 .IR open ), 78 and returns an associated file descriptor. 79 If the file is new, 80 the owner is set to the userid of the creating process group; 81 the group to that of the containing directory; 82 the permissions to 83 .I perm 84 ANDed with the permissions of the containing directory. 85 If the file already exists, 86 it is truncated to 0 length, 87 and the permissions, owner, and group remain unchanged. 88 The created file is a directory if the 89 .B DMDIR 90 bit is set in 91 .IR perm , 92 an exclusive-use file if the 93 .B DMEXCL 94 bit is set, and an append-only file if the 95 .B DMAPPEND 96 bit is set. 97 Exclusive-use files may be open for I/O by only one client at a time, 98 but the file descriptor may become invalid if no I/O is done 99 for an extended period; see 100 .IR open (9p). 101 .PP 102 .I Create 103 fails if the path up to the last element of 104 .I file 105 cannot be evaluated, if the user doesn't have write permission 106 in the final directory, if the file already exists and 107 does not permit the access defined by 108 .IR omode , 109 of if there there are no free file descriptors. 110 In the last case, the file may be created even when 111 an error is returned. 112 .\" If the file is new and the directory in which it is created is 113 .\" a union directory (see 114 .\" .IR intro (3)) 115 .\" then the constituent directory where the file is created 116 .\" depends on the structure of the union: see 117 .\" .IR bind (3). 118 .PP 119 Since 120 .I create 121 may succeed even if the file exists, a special mechanism is necessary 122 for those applications that require an atomic create operation. 123 If the 124 .B OEXCL 125 .RB ( 0x1000 ) 126 bit is set in the 127 .I mode 128 for a 129 .IR create, 130 the call succeeds only if the file does not already exist; 131 see 132 .IR open (9p) 133 for details. 134 .PP 135 .I Close 136 closes the file associated with a file descriptor. 137 Provided the file descriptor is a valid open descriptor, 138 .I close 139 is guaranteed to close it; there will be no error. 140 Files are closed automatically upon termination of a process; 141 .I close 142 allows the file descriptor to be reused. 143 .SH SOURCE 144 .B \*9/src/lib9 145 .SH SEE ALSO 146 .MR intro (3) , 147 .MR stat (3) 148 .SH DIAGNOSTICS 149 These functions set 150 .IR errstr . 151 .SH BUGS 152 Not all functionality is supported on all systems. 153 .PP 154 The 155 .B DMAPPEND 156 bit is not supported on any systems. 157 .PP 158 The implementation of 159 .B ORCLOSE 160 is to unlink the file after opening it, causing problems 161 in programs that try to access the file by name before it is closed. 162 .PP 163 To avoid name conflicts with the underlying system, 164 .I open 165 and 166 .I create 167 are preprocessor macros defined as 168 .IR p9open 169 and 170 .IR p9create ; 171 see 172 .MR intro (3) .