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.misc.JavaIOFileDescriptorAccess;

    33 import jdk.internal.misc.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 }