1 /*
2 * Copyright (c) 2003, 2018, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.io;
27
28 import java.util.ArrayList;
29 import java.util.List;
30 import java.util.Objects;
31
32 import jdk.internal.access.JavaIOFileDescriptorAccess;
33 import jdk.internal.access.SharedSecrets;
34 import jdk.internal.ref.PhantomCleanable;
35
36 /**
37 * Instances of the file descriptor class serve as an opaque handle
38 * to the underlying machine-specific structure representing an open
39 * file, an open socket, or another source or sink of bytes.
40 * The main practical use for a file descriptor is to create a
41 * {@link FileInputStream} or {@link FileOutputStream} to contain it.
42 * <p>
43 * Applications should not create their own file descriptors.
44 *
45 * @author Pavani Diwanji
46 * @since 1.0
47 */
48 public final class FileDescriptor {
49
50 private int fd;
51
52 private long handle;
53
54 private Closeable parent;
55 private List<Closeable> otherParents;
56 private boolean closed;
57
58 /**
59 * true, if file is opened for appending.
60 */
61 private boolean append;
62
63 static {
64 initIDs();
65 }
66
67 // Set up JavaIOFileDescriptorAccess in SharedSecrets
68 static {
69 SharedSecrets.setJavaIOFileDescriptorAccess(
70 new JavaIOFileDescriptorAccess() {
71 public void set(FileDescriptor fdo, int fd) {
72 fdo.set(fd);
73 }
74
75 public int get(FileDescriptor fdo) {
76 return fdo.fd;
77 }
78
79 public void setAppend(FileDescriptor fdo, boolean append) {
80 fdo.append = append;
81 }
82
83 public boolean getAppend(FileDescriptor fdo) {
84 return fdo.append;
85 }
86
87 public void close(FileDescriptor fdo) throws IOException {
88 fdo.close();
89 }
90
91 /* Register for a normal FileCleanable fd/handle cleanup. */
92 public void registerCleanup(FileDescriptor fdo) {
93 FileCleanable.register(fdo);
94 }
95
96 /* Register a custom PhantomCleanup. */
97 public void registerCleanup(FileDescriptor fdo,
98 PhantomCleanable<FileDescriptor> cleanup) {
99 fdo.registerCleanup(cleanup);
100 }
101
102 public void unregisterCleanup(FileDescriptor fdo) {
103 fdo.unregisterCleanup();
104 }
105
106 public void setHandle(FileDescriptor fdo, long handle) {
107 fdo.setHandle(handle);
108 }
109
110 public long getHandle(FileDescriptor fdo) {
111 return fdo.handle;
112 }
113 }
114 );
115 }
116
117 /**
118 * Cleanup in case FileDescriptor is not explicitly closed.
119 */
120 private PhantomCleanable<FileDescriptor> cleanup;
121
122 /**
123 * Constructs an (invalid) FileDescriptor object.
124 * The fd or handle is set later.
125 */
126 public FileDescriptor() {
127 fd = -1;
128 handle = -1;
129 }
130
131 /**
132 * Used for standard input, output, and error only.
133 * For Windows the corresponding handle is initialized.
134 * For Unix the append mode is cached.
135 * @param fd the raw fd number (0, 1, 2)
136 */
137 private FileDescriptor(int fd) {
138 this.fd = fd;
139 this.handle = getHandle(fd);
140 this.append = getAppend(fd);
141 }
142
143 /**
144 * A handle to the standard input stream. Usually, this file
145 * descriptor is not used directly, but rather via the input stream
146 * known as {@code System.in}.
147 *
148 * @see java.lang.System#in
149 */
150 public static final FileDescriptor in = new FileDescriptor(0);
151
152 /**
153 * A handle to the standard output stream. Usually, this file
154 * descriptor is not used directly, but rather via the output stream
155 * known as {@code System.out}.
156 * @see java.lang.System#out
157 */
158 public static final FileDescriptor out = new FileDescriptor(1);
159
160 /**
161 * A handle to the standard error stream. Usually, this file
162 * descriptor is not used directly, but rather via the output stream
163 * known as {@code System.err}.
164 *
165 * @see java.lang.System#err
166 */
167 public static final FileDescriptor err = new FileDescriptor(2);
168
169 /**
170 * Tests if this file descriptor object is valid.
171 *
172 * @return {@code true} if the file descriptor object represents a
173 * valid, open file, socket, or other active I/O connection;
174 * {@code false} otherwise.
175 */
176 public boolean valid() {
177 return (handle != -1) || (fd != -1);
178 }
179
180 /**
181 * Force all system buffers to synchronize with the underlying
182 * device. This method returns after all modified data and
183 * attributes of this FileDescriptor have been written to the
184 * relevant device(s). In particular, if this FileDescriptor
185 * refers to a physical storage medium, such as a file in a file
186 * system, sync will not return until all in-memory modified copies
187 * of buffers associated with this FileDescriptor have been
188 * written to the physical medium.
189 *
190 * sync is meant to be used by code that requires physical
191 * storage (such as a file) to be in a known state For
192 * example, a class that provided a simple transaction facility
193 * might use sync to ensure that all changes to a file caused
194 * by a given transaction were recorded on a storage medium.
195 *
196 * sync only affects buffers downstream of this FileDescriptor. If
197 * any in-memory buffering is being done by the application (for
198 * example, by a BufferedOutputStream object), those buffers must
199 * be flushed into the FileDescriptor (for example, by invoking
200 * OutputStream.flush) before that data will be affected by sync.
201 *
202 * @exception SyncFailedException
203 * Thrown when the buffers cannot be flushed,
204 * or because the system cannot guarantee that all the
205 * buffers have been synchronized with physical media.
206 * @since 1.1
207 */
208 public native void sync() throws SyncFailedException;
209
210 /* This routine initializes JNI field offsets for the class */
211 private static native void initIDs();
212
213 /*
214 * On Windows return the handle for the standard streams.
215 */
216 private static native long getHandle(int d);
217
218 /**
219 * Returns true, if the file was opened for appending.
220 */
221 private static native boolean getAppend(int fd);
222
223 /**
224 * Set the fd.
225 * Used on Unix and for sockets on Windows and Unix.
226 * If setting to -1, clear the cleaner.
227 * The {@link #registerCleanup} method should be called for new fds.
228 * @param fd the raw fd or -1 to indicate closed
229 */
230 @SuppressWarnings("unchecked")
231 synchronized void set(int fd) {
232 if (fd == -1 && cleanup != null) {
233 cleanup.clear();
234 cleanup = null;
235 }
236 this.fd = fd;
237 }
238
239 /**
240 * Set the handle.
241 * Used on Windows for regular files.
242 * If setting to -1, clear the cleaner.
243 * The {@link #registerCleanup} method should be called for new handles.
244 * @param handle the handle or -1 to indicate closed
245 */
246 @SuppressWarnings("unchecked")
247 void setHandle(long handle) {
248 if (handle == -1 && cleanup != null) {
249 cleanup.clear();
250 cleanup = null;
251 }
252 this.handle = handle;
253 }
254
255 /**
256 * Register a cleanup for the current handle.
257 * Used directly in java.io and indirectly via fdAccess.
258 * The cleanup should be registered after the handle is set in the FileDescriptor.
259 * @param cleanable a PhantomCleanable to register
260 */
261 @SuppressWarnings("unchecked")
262 synchronized void registerCleanup(PhantomCleanable<FileDescriptor> cleanable) {
263 Objects.requireNonNull(cleanable, "cleanable");
264 if (cleanup != null) {
265 cleanup.clear();
266 }
267 cleanup = cleanable;
268 }
269
270 /**
271 * Unregister a cleanup for the current raw fd or handle.
272 * Used directly in java.io and indirectly via fdAccess.
273 * Normally {@link #close()} should be used except in cases where
274 * it is certain the caller will close the raw fd and the cleanup
275 * must not close the raw fd. {@link #unregisterCleanup()} must be
276 * called before the raw fd is closed to prevent a race that makes
277 * it possible for the fd to be reallocated to another use and later
278 * the cleanup might be invoked.
279 */
280 synchronized void unregisterCleanup() {
281 if (cleanup != null) {
282 cleanup.clear();
283 }
284 cleanup = null;
285 }
286
287 /**
288 * Close the raw file descriptor or handle, if it has not already been closed.
289 * The native code sets the fd and handle to -1.
290 * Clear the cleaner so the close does not happen twice.
291 * Package private to allow it to be used in java.io.
292 * @throws IOException if close fails
293 */
294 @SuppressWarnings("unchecked")
295 synchronized void close() throws IOException {
296 unregisterCleanup();
297 close0();
298 }
299
300 /*
301 * Close the raw file descriptor or handle, if it has not already been closed
302 * and set the fd and handle to -1.
303 */
304 private native void close0() throws IOException;
305
306 /*
307 * Package private methods to track referents.
308 * If multiple streams point to the same FileDescriptor, we cycle
309 * through the list of all referents and call close()
310 */
311
312 /**
313 * Attach a Closeable to this FD for tracking.
314 * parent reference is added to otherParents when
315 * needed to make closeAll simpler.
316 */
317 synchronized void attach(Closeable c) {
318 if (parent == null) {
319 // first caller gets to do this
320 parent = c;
321 } else if (otherParents == null) {
322 otherParents = new ArrayList<>();
323 otherParents.add(parent);
324 otherParents.add(c);
325 } else {
326 otherParents.add(c);
327 }
328 }
329
330 /**
331 * Cycle through all Closeables sharing this FD and call
332 * close() on each one.
333 *
334 * The caller closeable gets to call close0().
335 */
336 @SuppressWarnings("try")
337 synchronized void closeAll(Closeable releaser) throws IOException {
338 if (!closed) {
339 closed = true;
340 IOException ioe = null;
341 try (releaser) {
342 if (otherParents != null) {
343 for (Closeable referent : otherParents) {
344 try {
345 referent.close();
346 } catch(IOException x) {
347 if (ioe == null) {
348 ioe = x;
349 } else {
350 ioe.addSuppressed(x);
351 }
352 }
353 }
354 }
355 } catch(IOException ex) {
356 /*
357 * If releaser close() throws IOException
358 * add other exceptions as suppressed.
359 */
360 if (ioe != null)
361 ex.addSuppressed(ioe);
362 ioe = ex;
363 } finally {
364 if (ioe != null)
365 throw ioe;
366 }
367 }
368 }
369 }