Add System.IO.char8, the encoding used by openBinaryFile,

and correct the documentation for hSetBinaryMode which claimed that
it was using the latin1 encoding when in fact it was using an
unchecked modulo-256 version of it.

libraries/base/GHC/IO/Encoding.hs

@@ -22,6 +22,7 @@ module GHC.IO.Encoding (
   utf16, utf16le, utf16be,
   utf32, utf32le, utf32be, 
   localeEncoding, fileSystemEncoding, foreignEncoding,
+  char8,
   mkTextEncoding,
   ) where
 
@@ -125,6 +126,16 @@ fileSystemEncoding = CodePage.mkLocaleEncoding RoundtripFailure
 foreignEncoding = CodePage.mkLocaleEncoding IgnoreCodingFailure
 #endif
 
+-- | An encoding in which Unicode code points are translated to bytes
+-- by taking the code point modulo 256.  When decoding, bytes are
+-- translated directly into the equivalent code point.
+--
+-- This encoding never fails in either direction.  However, encoding
+-- discards informaiton, so encode followed by decode is not the
+-- identity.
+char8 :: TextEncoding
+char8 = Latin1.latin1
+
 -- | Look up the named Unicode encoding.  May fail with 
 --
 --  * 'isDoesNotExistError' if the encoding is unknown
@@ -183,7 +194,7 @@ mkTextEncoding e = case mb_coding_failure_mode of
                                             ("unknown encoding:" ++ e)  Nothing Nothing)
 
 latin1_encode :: CharBuffer -> Buffer Word8 -> IO (CharBuffer, Buffer Word8)
-latin1_encode input output = fmap (\(_why,input',output') -> (input',output')) $ Latin1.latin1_encode input output -- unchecked, used for binary
+latin1_encode input output = fmap (\(_why,input',output') -> (input',output')) $ Latin1.latin1_encode input output -- unchecked, used for char8
 --latin1_encode = unsafePerformIO $ do mkTextEncoder Iconv.latin1 >>= return.encode
 
 latin1_decode :: Buffer Word8 -> CharBuffer -> IO (Buffer Word8, CharBuffer)

libraries/base/GHC/IO/Handle.hs

@@ -551,7 +551,7 @@ hIsTerminalDevice handle = do
 -- | Select binary mode ('True') or text mode ('False') on a open handle.
 -- (See also 'openBinaryFile'.)
 --
--- This has the same effect as calling 'hSetEncoding' with 'latin1', together
+-- This has the same effect as calling 'hSetEncoding' with 'char8', together
 -- with 'hSetNewlineMode' with 'noNewlineTranslation'.
 --
 hSetBinaryMode :: Handle -> Bool -> IO ()

libraries/base/System/IO.hs

@@ -201,6 +201,7 @@ module System.IO (
     utf16, utf16le, utf16be,
     utf32, utf32le, utf32be, 
     localeEncoding,
+    char8,
     mkTextEncoding,
 #endif