core/io/streams/c/c-docs.factor

   1 USING: help.markup help.syntax io io.files threads
   2 strings byte-arrays io.streams.plain ;
   3 IN: io.streams.c
   4
   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."
   7 { $subsection <c-reader> }
   8 { $subsection <c-writer> }
   9 "Underlying primitives used to implement the above:"
  10 { $subsection fopen }
  11 { $subsection fwrite }
  12 { $subsection fflush }
  13 { $subsection fclose }
  14 { $subsection fgetc }
  15 { $subsection fread }
  16 "The three standard file handles:"
  17 { $subsection stdin-handle }
  18 { $subsection stdout-handle }
  19 { $subsection stderr-handle } ;
  20
  21 ABOUT: "io.streams.c"
  22
  23 HELP: <c-reader> ( in -- stream )
  24 { $values { "in" "a C FILE* handle" } { "stream" "a new stream" } }
  25 { $description "Creates a stream which reads data by calling C standard library functions." }
  26 { $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;
  27
  28 HELP: <c-writer> ( out -- stream )
  29 { $values { "out" "a C FILE* handle" } { "stream" "a new stream" } }
  30 { $description "Creates a stream which writes data by calling C standard library functions." }
  31 { $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;
  32
  33 HELP: fopen ( path mode -- alien )
  34 { $values { "path" "a pathname string" } { "mode" "an access mode specifier" } { "alien" "a C FILE* handle" } }
  35 { $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." }
  36 { $errors "Throws an error if the file could not be opened." }
  37 { $notes "User code should call " { $link <file-reader> } " or " { $link <file-writer> } " to get a high level stream." } ;
  38
  39 HELP: fwrite ( string alien -- )
  40 { $values { "string" "a string" } { "alien" "a C FILE* handle" } }
  41 { $description "Writes a string of text to a C FILE* handle." }
  42 { $errors "Throws an error if the output operation failed." } ;
  43
  44 HELP: fflush ( alien -- )
  45 { $values { "alien" "a C FILE* handle" } }
  46 { $description "Forces pending output on a C FILE* handle to complete." }
  47 { $errors "Throws an error if the output operation failed." } ;
  48
  49 HELP: fclose ( alien -- )
  50 { $values { "alien" "a C FILE* handle" } }
  51 { $description "Closes a C FILE* handle." } ;
  52
  53 HELP: fgetc ( alien -- ch/f )
  54 { $values { "alien" "a C FILE* handle" } { "ch/f" "a character or " { $link f } } }
  55 { $description "Reads a single character from a C FILE* handle, and outputs " { $link f } " on end of file." }
  56 { $errors "Throws an error if the input operation failed." } ;
  57
  58 HELP: fread ( n alien -- str/f )
  59 { $values { "n" "a positive integer" } { "alien" "a C FILE* handle" } { "str/f" "a string or " { $link f } } }
  60 { $description "Reads a sequence of characters from a C FILE* handle, and outputs " { $link f } " on end of file." }
  61 { $errors "Throws an error if the input operation failed." } ;
  62
  63 HELP: stdin-handle
  64 { $values { "in" "a C FILE* handle" } }
  65 { $description "Outputs the console standard input file handle." } ;
  66
  67 HELP: stdout-handle
  68 { $values { "out" "a C FILE* handle" } }
  69 { $description "Outputs the console standard output file handle." } ;
  70
  71 HELP: stderr-handle
  72 { $values { "out" "a C FILE* handle" } }
  73 { $description "Outputs the console standard error file handle." } ;