1. When a stream is created for reading ( i.e. option flags is XNLS_OPT_READ), input data is expected to be encoded in the specified encoding eid. The converter gets the stream of data to process from a callback function: the provided read function fsync takes as parameters some general context vctx (provided to XNLSconvread), the file descriptor for this stream (specified with this call as fd) and a buffer buf where it puts up to bufsize bytes of data. This function must return the amount of data transfered, 0 when the end of file has been reached or a negative value to indicate an error condition.

2. When a stream is created for writing ( i.e. option flags is XNLS_OPT_WRITE), output data is encoded in the specified encoding eid. The converter outputs the stream of data it has processed using a callback function: the provided write function fsync takes as parameters some general context vctx (provided to XNLSconvwrite), the file descriptor for this stream (specified with this call as fd) and a buffer buf of bufsize bytes of data to save. This function is expected to return a non-zero value on success ( i.e. all data has been saved) and 0 on failure.

3. The option XNLS_OPT_NOBOM tells the routine not to try to find a BOM (Byte Order Mark) when opening a stream for reading. This BOM consists in a sequence of bytes at the beginning of the stream to identify the Unicode encoding used for the stream. Unless the option XNLS_OPT_NOBOM is used, this BOM detection is effective when the selected encoding is Unicode (either UTF-8, UTF-16 or UTF-32). When applied to a stream open for writing, this option disables the insertion of a BOM when creating a stream encoded in UT-F16 or UTF-32 (it is gnored for all other encodings).

4. The option XNLS_OPT_BOM forces the insertion of the BOM when openning a stream encoded in UTF-8 for writing (this encoding usually does not require a BOM).