I/O and Network

I/O and Network

General I/O

stdout

Global variable referring to the standard out stream.

source

stderr

Global variable referring to the standard error stream.

source

stdin

Global variable referring to the standard input stream.

source

open(f::Function, args...; kwargs....)

Apply the function f to the result of open(args...; kwargs...) and close the resulting file descriptor upon completion.

Examples

julia> open("myfile.txt", "w") do io
           write(io, "Hello world!")
       end;
julia> open(f->read(f, String), "myfile.txt")
"Hello world!"
julia> rm("myfile.txt")

source

open(filename::AbstractString; keywords...) -> IOStream

Open a file in a mode specified by five boolean keyword arguments:

Keyword	Description	Default
`read`	open for reading	`!write`
`write`	open for writing	`truncate \| append`
`create`	create if non-existent	`!read & write \| truncate \| append`
`truncate`	truncate to zero size	`!read & write`
`append`	seek to end	`false`

The default when no keywords are passed is to open files for reading only. Returns a stream for accessing the opened file.

source

open(filename::AbstractString, [mode::AbstractString]) -> IOStream

Alternate syntax for open, where a string-based mode specifier is used instead of the five booleans. The values of mode correspond to those from fopen(3) or Perl open, and are equivalent to setting the following boolean groups:

Mode	Description	Keywords
`r`	read	none
`w`	write, create, truncate	`write = true`
`a`	write, create, append	`append = true`
`r+`	read, write	`read = true, write = true`
`w+`	read, write, create, truncate	`truncate = true, read = true`
`a+`	read, write, create, append	`append = true, read = true`

Examples

julia> io = open("myfile.txt", "w");
julia> write(io, "Hello world!");
julia> close(io);
julia> io = open("myfile.txt", "r");
julia> read(io, String)
"Hello world!"
julia> write(io, "This file is read only")
ERROR: ArgumentError: write failed, IOStream is not writeable
[...]
julia> close(io)
julia> io = open("myfile.txt", "a");
julia> write(io, "This stream is not read only")
28
julia> close(io)
julia> rm("myfile.txt")

source

open(fd::OS_HANDLE) -> IO

Take a raw file descriptor wrap it in a Julia-aware IO type, and take ownership of the fd handle. Call open(Libc.dup(fd)) to avoid the ownership capture of the original handle.

Do not call this on a handle that’s already owned by some other part of the system.

source

open(command, mode::AbstractString, stdio=devnull)

Run command asynchronously. Like open(command, stdio; read, write) except specifying the read and write flags via a mode string instead of keyword arguments. Possible mode strings are:

Mode	Description	Keywords
`r`	read	none
`w`	write	`write = true`
`r+`	read, write	`read = true, write = true`
`w+`	read, write	`read = true, write = true`

source

open(command, stdio=devnull; write::Bool = false, read::Bool = !write)

Start running command asynchronously, and return a process::IO object. If read is true, then reads from the process come from the process’s standard output and stdio optionally specifies the process’s standard input stream. If write is true, then writes go to the process’s standard input and stdio optionally specifies the process’s standard output stream. The process’s standard error stream is connected to the current global stderr.

source

open(f::Function, command, args...; kwargs...)

Similar to open(command, args...; kwargs...), but calls f(stream) on the resulting process stream, then closes the input stream and waits for the process to complete. Returns the value returned by f.

source

IOStream

A buffered IO stream wrapping an OS file descriptor. Mostly used to represent files returned by open.

source

IOBuffer([data::AbstractVector{UInt8}]; keywords...) -> IOBuffer

Create an in-memory I/O stream, which may optionally operate on a pre-existing array.

It may take optional keyword arguments:

read, write, append: restricts operations to the buffer; see open for details.
truncate: truncates the buffer size to zero length.
maxsize: specifies a size beyond which the buffer may not be grown.
sizehint: suggests a capacity of the buffer (data must implement sizehint!(data, size)).

When data is not given, the buffer will be both readable and writable by default.

Examples

julia> io = IOBuffer();
julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
56
julia> String(take!(io))
"JuliaLang is a GitHub organization. It has many members."
julia> io = IOBuffer(b"JuliaLang is a GitHub organization.")
IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=35, maxsize=Inf, ptr=1, mark=-1)
julia> read(io, String)
"JuliaLang is a GitHub organization."
julia> write(io, "This isn't writable.")
ERROR: ArgumentError: ensureroom failed, IOBuffer is not writeable
julia> io = IOBuffer(UInt8[], read=true, write=true, maxsize=34)
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=34, ptr=1, mark=-1)
julia> write(io, "JuliaLang is a GitHub organization.")
34
julia> String(take!(io))
"JuliaLang is a GitHub organization"
julia> length(read(IOBuffer(b"data", read=true, truncate=false)))
4
julia> length(read(IOBuffer(b"data", read=true, truncate=true)))
0

source

IOBuffer(string::String)

Create a read-only IOBuffer on the data underlying the given string.

Examples

julia> io = IOBuffer("Haho");
julia> String(take!(io))
"Haho"
julia> String(take!(io))
"Haho"

source

take!(b::IOBuffer)

Obtain the contents of an IOBuffer as an array, without copying. Afterwards, the IOBuffer is reset to its initial state.

Examples

julia> io = IOBuffer();
julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
56
julia> String(take!(io))
"JuliaLang is a GitHub organization. It has many members."

source

fdio([name::AbstractString, ]fd::Integer[, own::Bool=false]) -> IOStream

Create an IOStream object from an integer file descriptor. If own is true, closing this object will close the underlying descriptor. By default, an IOStream is closed when it is garbage collected. name allows you to associate the descriptor with a named file.

source

flush(stream)

Commit all currently buffered writes to the given stream.

source

close(stream)

Close an I/O stream. Performs a flush first.

source

write(io::IO, x)
write(filename::AbstractString, x)

Write the canonical binary representation of a value to the given I/O stream or file. Return the number of bytes written into the stream. See also print to write a text representation (with an encoding that may depend upon io).

You can write multiple values with the same write call. i.e. the following are equivalent:

write(io, x, y...)
write(io, x) + write(io, y...)

Examples

julia> io = IOBuffer();
julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
56
julia> String(take!(io))
"JuliaLang is a GitHub organization. It has many members."
julia> write(io, "Sometimes those members") + write(io, " write documentation.")
44
julia> String(take!(io))
"Sometimes those members write documentation."

User-defined plain-data types without write methods can be written when wrapped in a Ref:

julia> struct MyStruct; x::Float64; end
julia> io = IOBuffer()
IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)
julia> write(io, Ref(MyStruct(42.0)))
8
julia> seekstart(io); read!(io, Ref(MyStruct(NaN)))
Base.RefValue{MyStruct}(MyStruct(42.0))

source

read(io::IO, T)

Read a single value of type T from io, in canonical binary representation.

read(io::IO, String)

Read the entirety of io, as a String.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization");
julia> read(io, Char)
'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)
julia> io = IOBuffer("JuliaLang is a GitHub organization");
julia> read(io, String)
"JuliaLang is a GitHub organization"

source

read(filename::AbstractString, args...)

Open a file and read its contents. args is passed to read: this is equivalent to open(io->read(io, args...), filename).

read(filename::AbstractString, String)

Read the entire contents of a file as a string.

source

read(s::IO, nb=typemax(Int))

Read at most nb bytes from s, returning a Vector{UInt8} of the bytes read.

source

read(s::IOStream, nb::Integer; all=true)

Read at most nb bytes from s, returning a Vector{UInt8} of the bytes read.

If all is true (the default), this function will block repeatedly trying to read all requested bytes, until an error or end-of-file occurs. If all is false, at most one read call is performed, and the amount of data returned is device-dependent. Note that not all stream types support the all option.

source

read(command::Cmd)

Run command and return the resulting output as an array of bytes.

source

read(command::Cmd, String)

Run command and return the resulting output as a String.

source

read!(stream::IO, array::AbstractArray)
read!(filename::AbstractString, array::AbstractArray)

Read binary data from an I/O stream or file, filling in array.

source

readbytes!(stream::IO, b::AbstractVector{UInt8}, nb=length(b))

Read at most nb bytes from stream into b, returning the number of bytes read. The size of b will be increased if needed (i.e. if nb is greater than length(b) and enough bytes could be read), but it will never be decreased.

source

readbytes!(stream::IOStream, b::AbstractVector{UInt8}, nb=length(b); all::Bool=true)

source

unsafe_read(io::IO, ref, nbytes::UInt)

Copy nbytes from the IO stream object into ref (converted to a pointer).

It is recommended that subtypes T<:IO override the following method signature to provide more efficient implementations: unsafe_read(s::T, p::Ptr{UInt8}, n::UInt)

source

unsafe_write(io::IO, ref, nbytes::UInt)

Copy nbytes from ref (converted to a pointer) into the IO object.

It is recommended that subtypes T<:IO override the following method signature to provide more efficient implementations: unsafe_write(s::T, p::Ptr{UInt8}, n::UInt)

source

position(s)

Get the current position of a stream.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> position(io)
5
julia> skip(io, 10);
julia> position(io)
15
julia> seekend(io);
julia> position(io)
35

source

seek(s, pos)

Seek a stream to the given position.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> read(io, Char)
'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)

source

seekstart(s)

Seek a stream to its beginning.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> read(io, Char)
'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)
julia> seekstart(io);
julia> read(io, Char)
'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)

source

seekend(s)

Seek a stream to its end.

source

skip(s, offset)

Seek a stream relative to the current position.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization.");
julia> seek(io, 5);
julia> skip(io, 10);
julia> read(io, Char)
'G': ASCII/Unicode U+0047 (category Lu: Letter, uppercase)

source

mark(s)

Add a mark at the current position of stream s. Return the marked position.

See also mark, unmark, reset.

source

eof(stream) -> Bool

Test whether an I/O stream is at end-of-file. If the stream is not yet exhausted, this function will block to wait for more data if necessary, and then return false. Therefore it is always safe to read one byte after seeing eof return false. eof will return false as long as buffered data is still available, even if the remote end of a connection is closed.

source

isreadonly(io) -> Bool

Determine whether a stream is read-only.

Examples

julia> io = IOBuffer("JuliaLang is a GitHub organization");
julia> isreadonly(io)
true
julia> io = IOBuffer();
julia> isreadonly(io)
false

source

iswritable(io) -> Bool

Return true if the specified IO object is writable (if that can be determined).

Examples

julia> open("myfile.txt", "w") do io
           print(io, "Hello world!");
           iswritable(io)
       end
true
julia> open("myfile.txt", "r") do io
           iswritable(io)
       end
false
julia> rm("myfile.txt")

source

isreadable(io) -> Bool

Return true if the specified IO object is readable (if that can be determined).

Examples

julia> open("myfile.txt", "w") do io
           print(io, "Hello world!");
           isreadable(io)
       end
false
julia> open("myfile.txt", "r") do io
           isreadable(io)
       end
true
julia> rm("myfile.txt")

source

isopen(object) -> Bool

Determine whether an object - such as a stream or timer – is not yet closed. Once an object is closed, it will never produce a new event. However, since a closed stream may still have data to read in its buffer, use eof to check for the ability to read data. Use the FileWatching package to be notified when a stream might be writable or readable.

Examples

julia> io = open("my_file.txt", "w+");
julia> isopen(io)
true
julia> close(io)
julia> isopen(io)
false

source

fd(stream)

Return the file descriptor backing the stream or file. Note that this function only applies to synchronous File‘s and IOStream‘s not to any of the asynchronous streams.

source

redirect_stdout([stream]) -> (rd, wr)

Create a pipe to which all C and Julia level stdout output will be redirected. Returns a tuple (rd, wr) representing the pipe ends. Data written to stdout may now be read from the rd end of the pipe. The wr end is given for convenience in case the old stdout object was cached by the user and needs to be replaced elsewhere.

If called with the optional stream argument, then returns stream itself.