1 USING: help.markup help.syntax io io.files threads
2 strings byte-arrays io.streams.plain alien math ;
5 ARTICLE: "io.streams.c" "ANSI C streams"
6 "C streams are found in the " { $vocab-link "io.streams.c" } " vocabulary; they are " { $link "stream-protocol" } " implementations which read and write C " { $snippet "FILE*" } " handles."
11 "Underlying primitives used to implement the above:"
21 "The three standard file handles:"
31 { $values { "handle" "a C FILE* handle" } { "stream" "a new stream" } }
32 { $description "Creates a stream which reads data by calling C standard library functions." }
33 { $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;
36 { $values { "handle" "a C FILE* handle" } { "stream" "a new stream" } }
37 { $description "Creates a stream which writes data by calling C standard library functions." }
38 { $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;
41 { $values { "path" "a pathname string" } { "mode" "an access mode specifier" } { "alien" "a C FILE* handle" } }
42 { $description "Opens a file named by " { $snippet "path" } ". The " { $snippet "mode" } " parameter should be something like " { $snippet "\"r\"" } " or " { $snippet "\"rw\"" } "; consult the " { $snippet "fopen(3)" } " manual page for details." }
43 { $errors "Throws an error if the file could not be opened." }
44 { $notes "User code should call " { $link <file-reader> } " or " { $link <file-writer> } " to get a high level stream." } ;
47 { $values { "data" c-ptr } { "length" integer } { "alien" "a C FILE* handle" } }
48 { $description "Writes some bytes to a C FILE* handle." }
49 { $errors "Throws an error if the output operation failed." } ;
52 { $values { "alien" "a C FILE* handle" } }
53 { $description "Forces pending output on a C FILE* handle to complete." }
54 { $errors "Throws an error if the output operation failed." } ;
57 { $values { "alien" "a C FILE* handle" } }
58 { $description "Closes a C FILE* handle." } ;
61 { $values { "alien" "a C FILE* handle" } { "byte/f" "an integer from 0 to 255 or " { $link f } } }
62 { $description "Reads a single byte from a C FILE* handle, and outputs " { $link f } " on end of file." }
63 { $errors "Throws an error if the input operation failed." } ;
66 { $values { "byte" "an integer from 0 to 255" } { "alien" "a C FILE* handle" } }
67 { $description "Writes a single byte to a C FILE* handle." }
68 { $errors "Throws an error if the output operation failed." } ;
71 { $values { "n" "a positive integer" } { "buf" c-ptr } { "alien" "a C FILE* handle" } { "count" integer } }
72 { $description "Reads " { $snippet "n" } " bytes from a C FILE* handle into the memory referenced by " { $snippet "buf" } ", and outputs the number of characters read. Zero is output on end of file." }
73 { $warning "This word does not check whether " { $snippet "buf" } " is large enough to accommodate the requested number of bytes. Memory corruption will occur if this is not the case." }
74 { $errors "Throws an error if the input operation failed." } ;
77 { $values { "alien" "a C FILE* handle" } }
78 { $description "Outputs the console standard input file handle." } ;
81 { $values { "alien" "a C FILE* handle" } }
82 { $description "Outputs the console standard output file handle." } ;
85 { $values { "alien" "a C FILE* handle" } }
86 { $description "Outputs the console standard error file handle." } ;