I/O and Network
- General I/O
- Text I/O

I/O and Network

General I/O

Base.stdout — Constant

1. stdout

Global variable referring to the standard out stream.

source

Base.stderr — Constant

1. stderr

Global variable referring to the standard error stream.

source

Base.stdin — Constant

1. stdin

Global variable referring to the standard input stream.

source

Base.open — Function

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

1. julia> open("myfile.txt", "w") do io
2. write(io, "Hello world!")
3. end;

5. julia> open(f->read(f, String), "myfile.txt")
6. "Hello world!"

8. julia> rm("myfile.txt")

source

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

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

1. julia> io = open("myfile.txt", "w");

3. julia> write(io, "Hello world!");

5. julia> close(io);

7. julia> io = open("myfile.txt", "r");

9. julia> read(io, String)
10. "Hello world!"

12. julia> write(io, "This file is read only")
13. ERROR: ArgumentError: write failed, IOStream is not writeable
14. [...]

16. julia> close(io)

18. julia> io = open("myfile.txt", "a");

20. julia> write(io, "This stream is not read only")
21. 28

23. julia> close(io)

25. julia> rm("myfile.txt")

Julia 1.5

The lock argument is available as of Julia 1.5.

source

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

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

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

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

1. IOStream

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

source

Base.IOBuffer — Type

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

1. julia> io = IOBuffer();

3. julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
4. 56

6. julia> String(take!(io))
7. "JuliaLang is a GitHub organization. It has many members."

9. julia> io = IOBuffer(b"JuliaLang is a GitHub organization.")
10. IOBuffer(data=UInt8[...], readable=true, writable=false, seekable=true, append=false, size=35, maxsize=Inf, ptr=1, mark=-1)

12. julia> read(io, String)
13. "JuliaLang is a GitHub organization."

15. julia> write(io, "This isn't writable.")
16. ERROR: ArgumentError: ensureroom failed, IOBuffer is not writeable

18. julia> io = IOBuffer(UInt8[], read=true, write=true, maxsize=34)
19. IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=34, ptr=1, mark=-1)

21. julia> write(io, "JuliaLang is a GitHub organization.")
22. 34

24. julia> String(take!(io))
25. "JuliaLang is a GitHub organization"

27. julia> length(read(IOBuffer(b"data", read=true, truncate=false)))
28. 4

30. julia> length(read(IOBuffer(b"data", read=true, truncate=true)))
31. 0

source

1. IOBuffer(string::String)

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

Examples

1. julia> io = IOBuffer("Haho");

3. julia> String(take!(io))
4. "Haho"

6. julia> String(take!(io))
7. "Haho"

source

Base.take! — Method

1. take!(b::IOBuffer)

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

Examples

1. julia> io = IOBuffer();

3. julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
4. 56

6. julia> String(take!(io))
7. "JuliaLang is a GitHub organization. It has many members."

source

Base.fdio — Function

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

1. flush(stream)

Commit all currently buffered writes to the given stream.

source

Base.close — Function

1. close(stream)

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

source

Base.write — Function

1. write(io::IO, x)
2. 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:

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

Examples

Consistent serialization:

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

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

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

Merging write calls:

1. julia> io = IOBuffer();

3. julia> write(io, "JuliaLang is a GitHub organization.", " It has many members.")
4. 56

6. julia> String(take!(io))
7. "JuliaLang is a GitHub organization. It has many members."

9. julia> write(io, "Sometimes those members") + write(io, " write documentation.")
10. 44

12. julia> String(take!(io))
13. "Sometimes those members write documentation."

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

1. julia> struct MyStruct; x::Float64; end

3. julia> io = IOBuffer()
4. IOBuffer(data=UInt8[...], readable=true, writable=true, seekable=true, append=false, size=0, maxsize=Inf, ptr=1, mark=-1)

6. julia> write(io, Ref(MyStruct(42.0)))
7. 8

9. julia> seekstart(io); read!(io, Ref(MyStruct(NaN)))
10. Base.RefValue{MyStruct}(MyStruct(42.0))

source

Base.read — Function

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

1. read(io::IO, String)

Read the entirety of io, as a String.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization");

3. julia> read(io, Char)
4. 'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)

6. julia> io = IOBuffer("JuliaLang is a GitHub organization");

8. julia> read(io, String)
9. "JuliaLang is a GitHub organization"

source

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

1. read(filename::AbstractString, String)

Read the entire contents of a file as a string.

source

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

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

source

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

1. read(command::Cmd)

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

source

1. read(command::Cmd, String)

Run command and return the resulting output as a String.

source

Base.read! — Function

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

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

source

Base.readbytes! — Function

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

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

source

Base.unsafe_read — Function

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

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

1. peek(stream[, T=UInt8])

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

Examples

1. julia> b = IOBuffer("julia");

3. julia> peek(b)
4. 0x6a

6. julia> position(b)
7. 0

9. julia> peek(b, Char)
10. '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

1. position(s)

Get the current position of a stream.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization.");

3. julia> seek(io, 5);

5. julia> position(io)
6. 5

8. julia> skip(io, 10);

10. julia> position(io)
11. 15

13. julia> seekend(io);

15. julia> position(io)
16. 35

source

Base.seek — Function

1. seek(s, pos)

Seek a stream to the given position.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization.");

3. julia> seek(io, 5);

5. julia> read(io, Char)
6. 'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)

source

Base.seekstart — Function

1. seekstart(s)

Seek a stream to its beginning.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization.");

3. julia> seek(io, 5);

5. julia> read(io, Char)
6. 'L': ASCII/Unicode U+004C (category Lu: Letter, uppercase)

8. julia> seekstart(io);

10. julia> read(io, Char)
11. 'J': ASCII/Unicode U+004A (category Lu: Letter, uppercase)

source

Base.seekend — Function

1. seekend(s)

Seek a stream to its end.

source

Base.skip — Function

1. skip(s, offset)

Seek a stream relative to the current position.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization.");

3. julia> seek(io, 5);

5. julia> skip(io, 10);

7. julia> read(io, Char)
8. 'G': ASCII/Unicode U+0047 (category Lu: Letter, uppercase)

source

Base.mark — Function

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

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

1. isreadonly(io) -> Bool

Determine whether a stream is read-only.

Examples

1. julia> io = IOBuffer("JuliaLang is a GitHub organization");

3. julia> isreadonly(io)
4. true

6. julia> io = IOBuffer();

8. julia> isreadonly(io)
9. false

source

Base.iswritable — Function

1. iswritable(io) -> Bool

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

Examples

1. julia> open("myfile.txt", "w") do io
2. print(io, "Hello world!");
3. iswritable(io)
4. end
5. true

7. julia> open("myfile.txt", "r") do io
8. iswritable(io)
9. end
10. false

12. julia> rm("myfile.txt")

source

Base.isreadable — Function

1. isreadable(io) -> Bool

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

Examples

1. julia> open("myfile.txt", "w") do io
2. print(io, "Hello world!");
3. isreadable(io)
4. end
5. false

7. julia> open("myfile.txt", "r") do io
8. isreadable(io)
9. end
10. true

12. julia> rm("myfile.txt")

source

Base.isopen — Function

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

1. julia> io = open("my_file.txt", "w+");

3. julia> isopen(io)
4. true

6. julia> close(io)

8. julia> isopen(io)
9. false

source

Base.fd — Function

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

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