factor/library/io/c-streams.facts

USING: help io io-internals threads ;

HELP: io-multiplex "( ms -- )"
{ $values { "ms" "a non-negative integer" } }
{ $description "Waits up to " { $snippet "ms" } " milliseconds for pending I/O requests to complete." }
{ $warning "If an I/O request completes during the time period, its continuation is resumed and the current one is not saved. If you need to delay execution for a period of time, use the higher-level " { $link sleep } " word instead." } ;

HELP: <file-reader> "( path -- stream )"
{ $values { "path" "a string" } { "stream" "an input stream" } }
{ $description "Outputs an input stream for reading from the specified path name." }
{ $errors "Throws an error if the file is unreadable." } ;

HELP: <file-writer> "( path -- stream )"
{ $values { "path" "a string" } { "stream" "an output stream" } }
{ $description "Outputs an input stream for writing to the specified path name." }
{ $errors "Throws an error if the file is unreadable." } ;

HELP: <client> "( host port -- stream )"
{ $values { "host" "a string" } { "port" "an integer between 0 and 65535" } { "stream" "a bidirectional stream" } }
{ $description "Connects to TCP/IP port number " { $code "port" } " on the host named by " { $code "host" } ", and outputs a bidirectional stream." }
{ $errors "Throws an error if domain name lookup fails, or if there is a connection cannot be established." } ;

HELP: <server> "( port -- server )"
{ $values  { "port" "an integer between 0 and 65535" } { "server" "a handle" } }
{ $description
    "Begins listening for connections to " { $snippet "port" } " on all network interfaces. The returned object responds to two generic words:"
    { $list
        { { $link stream-close } " - stops listening on the port and frees all associated resources" }
        { { $link accept } " - blocks until there is a connection" }
    }
}
{ $errors "Throws an error if the port is already in use, or if the OS forbits access." } ;

HELP: accept "( server -- stream )"
{ $values { "server" "a handle" } { "stream" "a bidirectional stream" } }
{ $description "Waits for a connection to a server socket created by " { $link <server> } ", and outputs a bidirectional stream when the connection has been established."
$terpri
"The client socket supports two accessor words to get the host name and port number of the incoming connection:"
{ $list { $link client-stream-host } { $link client-stream-port } } }
{ $errors "Throws an error if the server socket is closed or otherwise is unavailable." } ;

HELP: <c-stream> "( in out -- stream )"
{ $values { "in" "a C FILE* handle" } { "out" "a C FILE* handle" } }
{ $description "Creates a stream which reads and writes data by calling C standard library functions." }
{ $notes "Usually C streams are only used during bootstrap, and non-blocking OS-specific I/O routines are used during normal operation." } ;

HELP: fopen "( path mode -- alien )"
{ $values { "path" "a pathname string" } { "mode" "an access mode specifier" } { "alien" "a C FILE* handle" } }
{ $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." }
{ $errors "Throws an error if the file could not be opened." }
{ $notes "User code should call " { $link <file-reader> } " or " { $link <file-writer> } " to get a high level stream." } ;

HELP: fwrite "( string alien -- )"
{ $values { "string" "a string" } { "alien" "a C FILE* handle" } }
{ $description "Writes a string of text to a C FILE* handle." }
{ $errors "Throws an error if the output operation failed." } ;

HELP: fflush "( alien -- )"
{ $values { "alien" "a C FILE* handle" } }
{ $description "Forces pending output on a C FILE* handle to complete." }
{ $errors "Throws an error if the output operation failed." } ;

HELP: fclose "( alien -- )"
{ $values { "alien" "a C FILE* handle" } }
{ $description "Closes a C FILE* handle." } ;

HELP: fgetc "( alien -- ch )"
{ $values { "alien" "a C FILE* handle" } { "ch" "a character" } }
{ $description "Reads a single character from a C FILE* handle." } 
{ $errors "Throws an error if the input operation failed." } ;