X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fstream.c;h=a161a4b83437da93a84fc24d5489ec1f5ef1cfbd;hb=f19a194bd066ea4320c1c6b6b8c5a375f7787af5;hp=3c15127211dcf00e5667637299bcdc9039c6f847;hpb=2da183ac47f1157560dcd2c417f7f6a24ae72352;p=projects%2Fchimara%2Fchimara.git
diff --git a/libchimara/stream.c b/libchimara/stream.c
index 3c15127..a161a4b 100644
--- a/libchimara/stream.c
+++ b/libchimara/stream.c
@@ -103,7 +103,8 @@ glk_stream_iterate(strid_t str, glui32 *rockptr)
* @str: A stream.
*
* Retrieves the stream @str's rock value. See Rocks.
+ * linkend="chimara-Rocks">Rocks. Window streams always have rock 0; all
+ * other streams return whatever rock you created them with.
*
* Returns: A rock value.
*/
@@ -421,9 +422,22 @@ file_stream_new(frefid_t fileref, glui32 fmode, glui32 rock, gboolean unicode)
* 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). If
- * @fmode is %filemode_WriteAppend, the file mark is set to the end of 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.
+ *
+ *
+ * Note, again, that this doesn't match stdio's fopen() call very well. See
+ * the file mode constants.
+ *
+ *
+ * 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