[GHC] #8286: fdToHandle docs are wrong about non-blocking mode

13 Sep 2013

      #8286: fdToHandle docs are wrong about non-blocking mode
------------------------------------+-------------------------------------
       Reporter:  duncan            |             Owner:
           Type:  bug               |            Status:  new
       Priority:  normal            |         Milestone:
      Component:  libraries/unix    |           Version:  7.6.3
       Keywords:                    |  Operating System:  Unknown/Multiple
   Architecture:  Unknown/Multiple  |   Type of failure:  None/Unknown
     Difficulty:  Unknown           |         Test Case:
     Blocked By:                    |          Blocking:
Related Tickets:                    |
------------------------------------+-------------------------------------
 The docs for System.Posix.IO.fdToHandle state:

 {{{
 fdToHandle :: Fd -> IO HandleSource

 Converts an Fd into a Handle that can be used with the standard Haskell IO
 library (see System.IO).

 GHC only: this function has the side effect of putting the Fd into
 non-blocking mode (O_NONBLOCK) due to the way the standard IO library
 implements multithreaded I/O.
 }}}

 The final paragraph is wrong. The code no longer does this.
 System.Posix.IO.fdToHandle ends up calling GHC.IO.Handle.FD.fdToHandle
 which has this comment:
 {{{
 fdToHandle :: Posix.FD -> IO Handle
 fdToHandle fdint = do
    iomode <- Posix.fdGetMode fdint
    (fd,fd_type) <- FD.mkFD fdint iomode Nothing
             False{-is_socket-}
               -- NB. the is_socket flag is False, meaning that:
               --  on Windows we're guessing this is not a socket (XXX)
             False{-is_nonblock-}
               -- file descriptors that we get from external sources are
               -- not put into non-blocking mode, because that would affect
               -- other users of the file descriptor
 }}}

 So clearly, it is now deliberately not putting it into non-blocking mode.

 This can trip people up who expect that it does put it into non-blocking
 mode, when in fact they now have to do that manually.

 Fix is trivial: delete that paragraph from the docs for that function.

-- 
Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/8286
GHC http://www.haskell.org/ghc/
The Glasgow Haskell Compiler