factor/core/io/c-streams.facts

USING: help io io-internals threads c-streams network strings
byte-arrays ;

HELP: io-multiplex
{ $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>
{ $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>
{ $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>
{ $values { "host" string } { "port" "an integer between 0 and 65535" } { "stream" "a bidirectional stream" } }
{ $description "Opens a TCP/IP connection to port number " { $snippet "port" } " on the host named by " { $snippet "host" } ", and outputs a bidirectional stream." }
{ $errors "Throws an error if domain name lookup fails, or if the connection cannot be established." } ;

HELP: <server>
{ $values  { "port" "an integer between 0 and 65535" } { "server" "a handle" } }
{ $description
    "Begins listening for TCP/IP connections to " { $snippet "port" } " on all network interfaces. The returned object responds to two 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 forbids access." } ;

HELP: accept
{ $values { "server" "a handle" } { "client" "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."
$nl
"The new stream 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: <datagram>
{ $values { "port" "an integer between 0 and 65535" } { "datagram" "a handle" } }
{ $description "Creates a UDP/IP socket listening on " { $snippet "port" } ". The returned object responds to three words:"
    { $list
        { { $link stream-close } " - stops listening on the port and frees all associated resources" }
        { { $link receive } " - waits for a UDP/IP packet" }
        { { $link send } " - sends a UDP/IP packet" }
    }
}
{ $errors "Throws an error if the port is already in use, or if the OS forbids access." } ;

HELP: receive
{ $values { "datagram" "a datagram socket" } { "packet" byte-array } { "host" string } { "port" "an integer between 0 and 65535" } }
{ $description "Waits for an incoming UDP/IP packet on the given datagram socket. Outputs the packet data, as well as the sender's host name and port number." }
{ $errors "Throws an error if the packet could not be received." } ;

HELP: send
{ $values { "packet" byte-array } { "host" string } { "port" "an integer between 0 and 65535" } { "datagram" "a datagram socket" } }
{ $description "Sends a UDP/IP packet to the given datagram socket." }
{ $errors "Throws an error if the packet could not be sent." } ;

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 path name 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." } ;

HELP: c-stream-error
{ $error-description "This error is thrown when C stream I/O is in use and one of the TCP/IP networking words is called. C stream I/O will be in use if either the " { $snippet "-no-native-io" } " switch is passed to bootstrap (see " { $link "bootstrap-cli-args" } ") or if Factor does not have a native I/O implementation for your operating system." } ;