--- a/modules/libjar/nsIJARChannel.idl
+++ b/modules/libjar/nsIJARChannel.idl
@@ -34,11 +34,18 @@ interface nsIJARChannel : nsIChannel
      * This will work even without opening the channel.
      */
     readonly attribute nsIZipEntry zipEntry;
 
     /**
      * For child process, set this to make sure that a valid file descriptor of
      * JAR file is always provided when calling NSPRFileDesc().
      * Must be set before Open() or AsyncOpen() to be effective.
+     *
+     * Note that the file descriptor returned by NSPRFileDesc() is duplicated
+     * from the original, which shares its file offset with the original.  If
+     * the file offset is modified (ex: by lseek/read/write) on one of the
+     * shared descriptors, the offset is also changed for the other.
+     * It can be safely used only with operations that take absolute offsets,
+     * such as mmap/pread/pwrite.
      */
     void ensureChildFd();
 };

--- a/netwerk/ipc/RemoteOpenFileChild.h
+++ b/netwerk/ipc/RemoteOpenFileChild.h
@@ -27,23 +27,25 @@ namespace net {
 /**
  * RemoteOpenFileChild: a thin wrapper around regular nsIFile classes that does
  * IPC to open a file handle on parent instead of child.  Used when we can't
  * open file handle on child (don't have permission), but we don't want the
  * overhead of shipping all I/O traffic across IPDL.  Example: JAR files.
  *
  * To open a file handle with this class, AsyncRemoteFileOpen() must be called
  * first.  After the listener's OnRemoteFileOpenComplete() is called, if the
- * result is NS_OK, nsIFile.OpenNSPRFileDesc() may be called--once--to get the
- * file handle.
+ * result is NS_OK, nsIFile.OpenNSPRFileDesc() may be called to get a
+ * duplicated file descriptor.
  *
- * Note that calling Clone() on this class results in the filehandle ownership
- * being passed on to the new RemoteOpenFileChild. I.e. if
- * OnRemoteFileOpenComplete is called and then Clone(), OpenNSPRFileDesc() will
- * work in the cloned object, but not in the original.
+ * Note that the file descriptor returned by NSPRFileDesc() is duplicated from
+ * the original, which shares its file offset with the original.  If the file
+ * offset is modified (ex: by lseek/read/write) on one of the shared
+ * descriptors, the offset is also changed for the other.   It can be safely
+ * used only with operations that take absolute offsets, such as
+ * mmap/pread/pwrite.
  *
  * This class should only be instantiated in a child process.
  *
  */
 class RemoteOpenFileChild MOZ_FINAL
   : public PRemoteOpenFileChild
   , public nsIFile
   , public nsIHashable