I/O and Network

General I/O

Base.stdout — Constant

stdout

Global variable referring to the standard out stream.

source

Base.stderr — Constant

stderr

Global variable referring to the standard error stream.

source

Base.stdin — Constant

stdin

Global variable referring to the standard input stream.

source

Base.open — Function

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; lock = true, 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.

The lock keyword argument controls whether operations will be locked for safe multi-threaded access.

Julia 1.5

The lock argument is available as of Julia 1.5.

source

open(filename::AbstractString, [mode::AbstractString]; lock = true) -> 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`

The lock keyword argument controls whether operations will be locked for safe multi-threaded access.

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")

Julia 1.5

The lock argument is available as of Julia 1.5.

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.

Warn

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

Base.IOStream — Type

IOStream

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

source

Base.IOBuffer — Type

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

Base.take! — Method

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

Base.fdio — Function

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

Base.flush — Function

flush(stream)

Commit all currently buffered writes to the given stream.

source

Base.close — Function

close(stream)

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

source

Base.write — Function

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).

The endianness of the written value depends on the endianness of the host system. Convert to/from a fixed endianness when writing/reading (e.g. using htol and ltoh) to get results that are consistent across platforms.

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

Consistent serialization:

julia> fname = tempname(); # random temporary filename

julia> open(fname,"w") do f
           # Make sure we write 64bit integer in little-endian byte order
           write(f,htol(Int64(42)))
       end
8

julia> open(fname,"r") do f
           # Convert back to host byte order and host integer type
           Int(ltoh(read(f,Int64)))
       end
42

Merging write calls:

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

Base.read — Function

read(io::IO, T)

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

Note that Julia does not convert the endianness for you. Use ntoh or ltoh for this purpose.

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

Base.read! — Function

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

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

source

Base.readbytes! — Function

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

Base.unsafe_read — Function

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

Base.unsafe_write — Function

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

Base.peek — Function

peek(stream[, T=UInt8])

Read and return a value of type T from a stream without advancing the current position in the stream.

Examples

julia> b = IOBuffer("julia");

julia> peek(b)
0x6a

julia> position(b)
0

julia> peek(b, Char)
'j': ASCII/Unicode U+006A (category Ll: Letter, lowercase)

Julia 1.5

The method which accepts a type requires Julia 1.5 or later.

source

Base.position — Function

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

Base.seek — Function

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

Base.seekstart — Function

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

Base.seekend — Function

seekend(s)

Seek a stream to its end.

source

Base.skip — Function

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

Base.mark — Function

mark(s)

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

See also mark, unmark, reset.

source

Base.eof — Function

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

Base.isreadonly — Function

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

Base.iswritable — Function

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

Base.isreadable — Function

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

Base.isopen — Function

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

Base.fd — Function

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

Base.redirect_stdout — Function

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.

Note