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

   1 USING: help.markup help.syntax io io.files threads
   2 strings byte-arrays io.streams.plain alien math ;
   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     fputc
  18     fgetc
  19     fread-unsafe
  20 }
  21 "The three standard file handles:"
  22 { $subsections
  23     stdin-handle
  24     stdout-handle
  25     stderr-handle
  26 } ;
  27
  28 ABOUT: "io.streams.c"
  29
  30 HELP: <c-reader>
  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." } ;
  34
  35 HELP: <c-writer>
  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." } ;
  39
  40 HELP: fopen
  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." } ;
  45
  46 HELP: fwrite
  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." } ;
  50
  51 HELP: fflush
  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." } ;
  55
  56 HELP: fclose
  57 { $values { "alien" "a C FILE* handle" } }
  58 { $description "Closes a C FILE* handle." } ;
  59
  60 HELP: fgetc
  61 { $values { "alien" "a C FILE* handle" } { "byte/f" { $maybe "an integer from 0 to 255" } } }
  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." } ;
  64
  65 HELP: fputc
  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." } ;
  69
  70 HELP: fread-unsafe
  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." } ;
  75
  76 HELP: stdin-handle
  77 { $values { "alien" "a C FILE* handle" } }
  78 { $description "Outputs the console standard input file handle." } ;
  79
  80 HELP: stdout-handle
  81 { $values { "alien" "a C FILE* handle" } }
  82 { $description "Outputs the console standard output file handle." } ;
  83
  84 HELP: stderr-handle
  85 { $values { "alien" "a C FILE* handle" } }
  86 { $description "Outputs the console standard error file handle." } ;