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