[Question] purpose and encoding of `ioe_filename`

[hasufell]

IOException has the following definition:

-- |Exceptions that occur in the @IO@ monad.
-- An @IOException@ records a more specific error type, a descriptive
-- string and maybe the handle that was used when the error was
-- flagged.
data IOException
 = IOError {
     ioe_handle   :: Maybe Handle,   -- the handle used by the action flagging
                                     -- the error.
     ioe_type     :: IOErrorType,    -- what it was.
     ioe_location :: String,         -- location.
     ioe_description :: String,      -- error type specific information.
     ioe_errno    :: Maybe CInt,     -- errno leading to this error, if any.
     ioe_filename :: Maybe FilePath  -- filename the error is related to.
   }

Since ioe_filename is Maybe FilePath, APIs that use ByteString or the new OsPath have an awkward situation, where they have to decide what to do:

1. set the field to Nothing and be done
2. just use unpack (so convert [Word8] to [Char])... printing may look like garbage on UTF-8 configured systems
3. use e.g. decodeFS, which is the closest match to base API behavior at the FFI boundary, but it's not well-defined for non-utf8 encodings
4. use something like decodeWith (mkUTF8 TransliterateCodingFailure), which never fails and replaces with the closest visual match upon an illegal sequences

This confusion has stirred up debate over at unix: haskell/unix#279

The main question here really is: should ioe_filename allow the caller to recover the original filename or is it just a descriptive field?

And then: if the former, which encoding do we pick? Right now, the unfortunate situation is that System.Posix.PosixPath.FilePath uses method 4 and System.Posix.ByteString.FilePath uses method 2. That's clearly undesirable. If we go for method 2 for both, how does the caller know? IMO, this needs to be documented in base. No one will look for this information in the unix modules, nor anticipate that behavior.

@bgamari @mpickering ... do GHC devs have an opinion?

[ocharles]

Does unix have to throw an IOException? Is the breakage too severe to use a different exception type that doesn't do any decoding of the path at all? Feel free to dismiss this as off topic of you feel it's not relevant

[hasufell]

My suggestion so far is:

• just make things consistent with the historical decision in System.Posix.ByteString.FilePath Make error strings consistent unix#288
• document directly in base that unix (or other packages) may provide a custom "encoding" for ioe_filename and not follow the base FFI logic

[bgamari]

In my opinion ioe_filename should merely be a descriptive field to aid in debugging. I think it would be fine to document this fact and would be happy to do so if there is consensus around this.

[hasufell]

should merely be a descriptive field to aid in debugging

In that case, the better decision in unix would then be to use decodeFS, which mimics what base does at the outer FFI layer. However, it can fail... I guess we can just catch exceptions and then set ioe_filename = Nothing in that case?

[hasufell]

Alternative implemented here: haskell/unix#289

[hasufell]

Alternative implemented here: haskell/unix#289

We're settling for this solution.

It may break some users test suites if their filenames contain non-ascii and if they inspect IOException.

[hasufell]

documentation PR sent for base: https://gitlab.haskell.org/ghc/ghc/-/merge_requests/10964