Summary of Steps

The following steps are required to create a user-defined stream in foreign code, such as C. The stream is represented in C as a pointer to a QP_stream structure. It can then be converted back to Prolog stream representation through stream_code/2. The predicate stream_code/2 converts, in either direction, between Prolog and C representations of a stream.

  1. Define the user-defined stream structure, containing fields required to operate the stream. (see fli-ios-cps-sst)
  2. Prepare creation of the user-defined stream. This usually requires a function to perform the following steps:
    1. Open the I/O channel, e.g. open a file or set up inter-process communication. (see fli-ios-cps-opn)
    2. Allocate memory for the user-defined stream and set values in the fields of the allocated user-defined stream. (see fli-ios-cps-all)
    3. Set up the default values for the QP_stream part of the user-defined stream through QU_stream_param() and modify these values as necessary. (see fli-ios-cps-sqs)
    4. Initialize the remaining fields of QP_stream structure used internally by the Prolog system through QP_prepare_stream() and register the created stream through QP_register_stream(). (see fli-ios-cps-ire)
    5. If the stream is a tty stream, register the stream to its tty group through QP_add_tty(). (see fli-ios-cps-tty)
  3. Implement the bottom layer functions to be used for the stream. These may include read, write, flush, seek and close functions. (see fli-ios-bot)

These steps are described in more detail in the remainder of this section. An example of creating a stream for a binary file in one of read, write or append modes is discussed. The example is written in C although it can also be written in other languages, such as Pascal or Fortran.

The example opens a file as a binary stream. The characters input from or output to the stream are exactly the same as stored in file. Seeking to a random byte position and flushing output are permitted in the stream. The first example lists complete source code (see fli-ios-uds). Note that binary streams are in fact supported in the system.