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) .