1 cfa37a7b 2004-04-10 devnull .TH OPEN 3
3 cfa37a7b 2004-04-10 devnull open, create, close \- open a file for reading or writing, create file
4 cfa37a7b 2004-04-10 devnull .SH SYNOPSIS
5 cfa37a7b 2004-04-10 devnull .B #include <u.h>
7 cfa37a7b 2004-04-10 devnull .B #include <libc.h>
10 cfa37a7b 2004-04-10 devnull int open(char *file, int omode)
13 cfa37a7b 2004-04-10 devnull int create(char *file, int omode, ulong perm)
16 cfa37a7b 2004-04-10 devnull int close(int fd)
17 cfa37a7b 2004-04-10 devnull .SH DESCRIPTION
19 cfa37a7b 2004-04-10 devnull opens the
21 cfa37a7b 2004-04-10 devnull for I/O and returns an associated file descriptor.
23 cfa37a7b 2004-04-10 devnull is one of
24 cfa37a7b 2004-04-10 devnull .BR OREAD ,
25 cfa37a7b 2004-04-10 devnull .BR OWRITE ,
26 cfa37a7b 2004-04-10 devnull .BR ORDWR ,
28 cfa37a7b 2004-04-10 devnull .BR OEXEC ,
29 cfa37a7b 2004-04-10 devnull asking for permission to read, write, read and write, or execute, respectively.
30 cfa37a7b 2004-04-10 devnull In addition, there are three values that can be ORed with the
31 cfa37a7b 2004-04-10 devnull .IR omode :
32 cfa37a7b 2004-04-10 devnull .B OTRUNC
33 cfa37a7b 2004-04-10 devnull says to truncate the file
34 cfa37a7b 2004-04-10 devnull to zero length before opening it;
35 cfa37a7b 2004-04-10 devnull .B OCEXEC
36 cfa37a7b 2004-04-10 devnull says to close the file when an
37 bf8a59fa 2004-04-11 devnull .IR exec (3)
40 cfa37a7b 2004-04-10 devnull system call is made;
42 cfa37a7b 2004-04-10 devnull .B ORCLOSE
43 cfa37a7b 2004-04-10 devnull says to remove the file when it is closed (by everyone who has a copy of the file descriptor).
45 cfa37a7b 2004-04-10 devnull fails if the file does not exist or the user does not have
46 cfa37a7b 2004-04-10 devnull permission to open it for the requested purpose
48 bf8a59fa 2004-04-11 devnull .IR stat (3)
49 cfa37a7b 2004-04-10 devnull for a description of permissions).
50 cfa37a7b 2004-04-10 devnull The user must have write permission on the
53 cfa37a7b 2004-04-10 devnull .B OTRUNC
54 cfa37a7b 2004-04-10 devnull bit is set.
57 cfa37a7b 2004-04-10 devnull system call
58 cfa37a7b 2004-04-10 devnull (unlike the implicit
61 bf8a59fa 2004-04-11 devnull .IR exec (3)),
63 cfa37a7b 2004-04-10 devnull is actually identical to
64 cfa37a7b 2004-04-10 devnull .BR OREAD .
66 cfa37a7b 2004-04-10 devnull .I Create
67 cfa37a7b 2004-04-10 devnull creates a new
69 cfa37a7b 2004-04-10 devnull or prepares to rewrite an existing
70 cfa37a7b 2004-04-10 devnull .IR file ,
71 cfa37a7b 2004-04-10 devnull opens it according to
73 cfa37a7b 2004-04-10 devnull (as described for
74 cfa37a7b 2004-04-10 devnull .IR open ),
75 cfa37a7b 2004-04-10 devnull and returns an associated file descriptor.
76 cfa37a7b 2004-04-10 devnull If the file is new,
77 cfa37a7b 2004-04-10 devnull the owner is set to the userid of the creating process group;
78 cfa37a7b 2004-04-10 devnull the group to that of the containing directory;
79 cfa37a7b 2004-04-10 devnull the permissions to
81 cfa37a7b 2004-04-10 devnull ANDed with the permissions of the containing directory.
82 cfa37a7b 2004-04-10 devnull If the file already exists,
83 cfa37a7b 2004-04-10 devnull it is truncated to 0 length,
84 cfa37a7b 2004-04-10 devnull and the permissions, owner, and group remain unchanged.
85 cfa37a7b 2004-04-10 devnull The created file is a directory if the
87 cfa37a7b 2004-04-10 devnull bit is set in
88 cfa37a7b 2004-04-10 devnull .IR perm ,
89 cfa37a7b 2004-04-10 devnull an exclusive-use file if the
90 cfa37a7b 2004-04-10 devnull .B DMEXCL
91 cfa37a7b 2004-04-10 devnull bit is set, and an append-only file if the
92 cfa37a7b 2004-04-10 devnull .B DMAPPEND
93 cfa37a7b 2004-04-10 devnull bit is set.
94 cfa37a7b 2004-04-10 devnull Exclusive-use files may be open for I/O by only one client at a time,
95 cfa37a7b 2004-04-10 devnull but the file descriptor may become invalid if no I/O is done
96 cfa37a7b 2004-04-10 devnull for an extended period; see
97 058b0118 2005-01-03 devnull .IR open (9p).
99 cfa37a7b 2004-04-10 devnull .I Create
100 cfa37a7b 2004-04-10 devnull fails if the path up to the last element of
102 cfa37a7b 2004-04-10 devnull cannot be evaluated, if the user doesn't have write permission
103 cfa37a7b 2004-04-10 devnull in the final directory, if the file already exists and
104 cfa37a7b 2004-04-10 devnull does not permit the access defined by
105 cfa37a7b 2004-04-10 devnull .IR omode ,
106 cfa37a7b 2004-04-10 devnull of if there there are no free file descriptors.
107 cfa37a7b 2004-04-10 devnull In the last case, the file may be created even when
108 cfa37a7b 2004-04-10 devnull an error is returned.
109 058b0118 2005-01-03 devnull .\" If the file is new and the directory in which it is created is
110 058b0118 2005-01-03 devnull .\" a union directory (see
111 058b0118 2005-01-03 devnull .\" .IR intro (3))
112 058b0118 2005-01-03 devnull .\" then the constituent directory where the file is created
113 058b0118 2005-01-03 devnull .\" depends on the structure of the union: see
114 058b0118 2005-01-03 devnull .\" .IR bind (3).
117 cfa37a7b 2004-04-10 devnull .I create
118 cfa37a7b 2004-04-10 devnull may succeed even if the file exists, a special mechanism is necessary
119 cfa37a7b 2004-04-10 devnull for those applications that require an atomic create operation.
121 cfa37a7b 2004-04-10 devnull .B OEXCL
122 cfa37a7b 2004-04-10 devnull .RB ( 0x1000 )
123 cfa37a7b 2004-04-10 devnull bit is set in the
126 cfa37a7b 2004-04-10 devnull .IR create,
127 cfa37a7b 2004-04-10 devnull the call succeeds only if the file does not already exist;
129 058b0118 2005-01-03 devnull .IR open (9p)
130 cfa37a7b 2004-04-10 devnull for details.
132 cfa37a7b 2004-04-10 devnull .I Close
133 cfa37a7b 2004-04-10 devnull closes the file associated with a file descriptor.
134 cfa37a7b 2004-04-10 devnull Provided the file descriptor is a valid open descriptor,
135 cfa37a7b 2004-04-10 devnull .I close
136 cfa37a7b 2004-04-10 devnull is guaranteed to close it; there will be no error.
137 cfa37a7b 2004-04-10 devnull Files are closed automatically upon termination of a process;
138 cfa37a7b 2004-04-10 devnull .I close
139 cfa37a7b 2004-04-10 devnull allows the file descriptor to be reused.
140 cfa37a7b 2004-04-10 devnull .SH SOURCE
141 058b0118 2005-01-03 devnull .B /usr/local/plan9/src/lib9
142 cfa37a7b 2004-04-10 devnull .SH SEE ALSO
143 bf8a59fa 2004-04-11 devnull .IR intro (3),
144 bf8a59fa 2004-04-11 devnull .IR stat (3)
145 cfa37a7b 2004-04-10 devnull .SH DIAGNOSTICS
146 cfa37a7b 2004-04-10 devnull These functions set
147 cfa37a7b 2004-04-10 devnull .IR errstr .
