Window Streams

Every window has an output stream associated with it. This is created automatically, with filemode_Write, when you open the window. You get it with glk_window_get_stream(). Window streams always have rock value 0.

A window stream cannot be closed with glk_stream_close(). It is closed automatically when you close its window with glk_window_close().

Only printable characters (including newline) may be printed to a window stream. See Character Encoding.

Memory Streams

You can open a stream which reads from or writes to a space in memory. See glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a memory stream, you specify a buffer to which the stream's output will be written, and its length buflen .

When outputting, if more than buflen characters are written to the stream, all of them beyond the buffer length will be thrown away, so as not to overwrite the buffer. (The character count of the stream will still be maintained correctly. That is, it will count the number of characters written into the stream, not the number that fit into the buffer.)

If the buffer is NULL, or for that matter if buflen is zero, then everything written to the stream is thrown away. This may be useful if you are interested in the character count.

When inputting, if more than buflen characters are read from the stream, the stream will start returning -1 (signalling end-of-file.) If the buffer is NULL, the stream will always return end-of-file.

The data is written to the buffer exactly as it was passed to the printing functions (glk_put_char(), etc.); input functions will read the data exactly as it exists in memory. No platform-dependent cookery will be done on it.

Whether reading or writing, the contents of the buffer are undefined until the stream is closed. The library may store the data there as it is written, or deposit it all in a lump when the stream is closed. It is illegal to change the contents of the buffer while the stream is open.

File Streams

You can open a stream which reads from or writes to a disk file. See glk_stream_open_file() and glk_stream_open_file_uni().

The file may be written in text or binary mode; this is determined by the file reference you open the stream with. Similarly, platform-dependent attributes such as file type are determined by the file reference. See File References.

Resource Streams

You can open a stream which reads from (but not writes to) a resource file.

glk_stream_open_memory ()

strid_t
glk_stream_open_memory (char *buf,
                        glui32 buflen,
                        glui32 fmode,
                        glui32 rock);

Opens a stream which reads from or writes to a space in memory. buf points to the buffer where output will be read from or written to. buflen is the length of the buffer.

Unicode values (characters greater than 255) cannot be written to the buffer. If you try, they will be stored as 0x3F ("?") characters.

glk_stream_open_memory_uni ()

strid_t
glk_stream_open_memory_uni (glui32 *buf,
                            glui32 buflen,
                            glui32 fmode,
                            glui32 rock);

Works just like glk_stream_open_memory(), except that the buffer is an array of 32-bit words, instead of bytes. This allows you to write and read any Unicode character. The buflen is the number of words, not the number of bytes.

glk_stream_open_file ()

strid_t
glk_stream_open_file (frefid_t fileref,
                      glui32 fmode,
                      glui32 rock);

Opens a stream which reads to or writes from a disk file. If fmode is filemode_Read, the file must already exist; for the other modes, an empty file is created if none exists. If fmode is filemode_Write, and the file already exists, it is truncated down to zero length (an empty file); the other modes do not truncate. If fmode is filemode_WriteAppend, the file mark is set to the end of the file.

If the filemode requires the file to exist, but the file does not exist, glk_stream_open_file() returns NULL.

The file may be read or written in text or binary mode; this is determined by the fileref argument. Similarly, platform-dependent attributes such as file type are determined by fileref . See File References.

When writing in binary mode, Unicode values (characters greater than 255) cannot be written to the file. If you try, they will be stored as 0x3F ("?") characters. In text mode, Unicode values may be stored exactly, approximated, or abbreviated, depending on what the platform's text files support.

glk_stream_open_file_uni ()

strid_t
glk_stream_open_file_uni (frefid_t fileref,
                          glui32 fmode,
                          glui32 rock);

This works just like glk_stream_open_file(), except that in binary mode, characters are written and read as four-byte (big-endian) values. This allows you to write any Unicode character.

In text mode, the file is written and read in a platform-dependent way, which may or may not handle all Unicode characters. A text-mode file created with glk_stream_open_file_uni() may have the same format as a text-mode file created with glk_stream_open_file(); or it may use a more Unicode-friendly format.

glk_stream_open_resource ()

strid_t
glk_stream_open_resource (glui32 filenum,
                          glui32 rock);

Open the given data resource for reading (only), as a normal stream.

If no resource chunk of the given number exists, the open function returns NULL.

As with file streams, a binary resource stream reads the resource as bytes. A text resource stream reads characters encoded as Latin-1.

When reading from a resource stream, newlines are not remapped, even if they normally would be when reading from a text file on the host OS. If you read a line (glk_get_line_stream() or glk_get_line_stream_uni()), a Unix newline (0x0A) terminates the line.

glk_stream_open_resource_uni ()

strid_t
glk_stream_open_resource_uni (glui32 filenum,
                              glui32 rock);

Open the given data resource for reading (only), as a Unicode stream. See glk_stream_open_resource() for more information.

As with file streams, a binary resource stream reads the resource as four-byte (big-endian) words. A text resource stream reads characters encoded as UTF-8.