IO

Usage

use IO;

or

import IO;

Submodules

Support for a variety of kinds of input and output.

Note

All Chapel programs automatically include write, writeln and writef.

Input/output (I/O) facilities in Chapel include the types file and channel; the constants stdin, stdout and stderr; the functions open, file.close, file.reader, file.writer, channel.read, channel.write, and many others.

I/O Overview

A file in Chapel identifies a file in the underlying operating system. Reads and writes to a file are done via one or more channels associated with the file. Each channel uses a buffer to provide sequential read or write access to its file, optionally starting at an offset.

For example, the following program opens a file and writes an integer to it:

// open the file "test-file.txt" for writing, creating it if
// it does not exist yet.
var myFile = open("test-file.txt", iomode.cw);

// create a writing channel starting at file offset 0
// (start and end offsets can be specified when creating the
// channel)
var myWritingChannel = myFile.writer();

var x: int = 17;

// This function will write the human-readable text version of x;
// binary I/O is also possible.
myWritingChannel.write(x);

// Now test-file.txt contains:
// 17

Then, the following program can be used to read the integer:

// open the file "test-file.txt" for reading only
var myFile = open("test-file.txt", iomode.r);

// create a reading channel starting at file offset 0
// (start and end offsets can be specified when creating the
// channel)
var myReadingChannel = myFile.reader();

var x: int;

// Now read a textual integer. Note that the
// channel.read function returns a bool to indicate
// if it read something or if the end of the file
// was reached before something could be read.
var readSomething = myReadingChannel.read(x);

writeln("Read integer ", x);
// prints out:
// 17

The read functions allow one to read values into variables as the following example demonstrates. It shows three ways to read values into a pair of variables x and y.

var x: int;
var y: real;
/* reading into variable expressions, returning
   true if the values were read, false on EOF */
var ok:bool = read(x, y);

/* reading via a single type argument */
x = read(int);
y = read(real);

/* reading via multiple type arguments */
(x, y) = read(int, real);

Design Rationale

Since channels operate independently, concurrent I/O to the same open file is possible without contending for locks. Furthermore, since the channel (and not the file) stores the current file offset, it is straightforward to create programs that access the same open file in parallel. Note that such parallel access is not possible in C when multiple threads are using the same FILE* to write to different regions of a file because of the race condition between fseek and fwrite. Because of these issues, Chapel programmers wishing to perform I/O will need to know how to open files as well as create channels.

I/O Styles

Warning

iostyle is now deprecated. We are working on creating a full-featured replacement for it but in the meantime the Formatted I/O facilities are still available to control formatting.

Reading and writing of Chapel’s basic types is regulated by an applicable iostyle. In particular, the I/O style controls whether binary or text I/O should be performed. For binary I/O it specifies, for example, byte order and string encoding. For text I/O it specifies string representation; the base, field width and precision for numeric types; and so on. Each channel has an associated I/O style. It applies to all read/write operations on that channel, except when the program specifies explicitly an I/O style for a particular read or write.

See the definition for the iostyle type. This type represents I/O styles and provides details on formatting and other representation choices.

The default value of the iostyle type is undefined. However, the compiler-generated constructor is available. It can be used to generate the default I/O style, with or without modifications. In addition, the function defaultIOStyle will return the default I/O style just as new iostyle() will.

The I/O style for an I/O operation can be provided through an optional style= argument in a variety of places:

Note that file.reader, or file.writer will copy the file’s I/O style if a style= argument is not provided. Also note that I/O functions on channels will by default use the I/O style stored with that channel.

A channel’s I/O style may be retrieved using channel._style and set using channel._set_style. These functions should only be called while the channel lock is held, however. See Synchronization of Channel Data and Avoiding Data Races for more information on channel locks.

As an example for specifying an I/O style, the code below specifies the minimum width for writing numbers so array elements are aligned in the output:

stdout.writeln(MyArray, new iostyle(min_width=10));

I/O facilities in Chapel also include several other ways to control I/O formatting. There is support for formatted I/O with FormattedIO.channel.readf and FormattedIO.channel.writef. Also note that record or class implementations can provide custom functions implementing read or write operations for that type (see The readThis() and writeThis() Methods).

Files

There are several functions that open a file and return a file including open, opentmp, openmem, openfd, and openfp.

Once a file is open, it is necessary to create associated channel(s) - see file.reader and file.writer - to write to and/or read from the file.

Use the file.fsync function to explicitly synchronize the file to ensure that file data is committed to the file’s underlying device for persistence.

To release any resources associated with a file, it is necessary to first close any channels using that file (with channel.close) and then the file itself (with file.close).

Note

Escaped strings can be used for paths on systems where UTF-8 file names are not enforced.

Functions for Channel Creation

file.writer creates a channel for writing to a file, and file.reader create a channel for reading from a file.

Synchronization of Channel Data and Avoiding Data Races

Channels (and files) contain locks in order to keep their operation safe for multiple tasks. When creating a channel, it is possible to disable the lock (for performance reasons) by passing locking=false to e.g. file.writer(). Some channel methods - in particular those beginning with the underscore - should only be called on locked channels. With these methods, it is possible to get or set the channel style, or perform I/O “transactions” (see channel.mark and channel._mark). To use these methods, first lock the channel with channel.lock, call the methods you need, then unlock the channel with channel.unlock. Note that in the future, we may move to alternative ways of calling these functions that guarantee that they are not called on a channel without the appropriate locking.

Besides data races that can occur if locking is not used in channels when it should be, it is also possible for there to be data races on file data that is buffered simultaneously in multiple channels. The main way to avoid such data races is the channel.flush synchronization operation. channel.flush will make all writes to the channel, if any, available to concurrent viewers of its associated file, such as other channels or other applications accessing this file concurrently. See the note below for more details on the situation in which this kind of data race can occur.

Note

Since channels can buffer data until channel.flush is called, it is possible to write programs that have undefined behaviour because of race conditions on channel buffers. In particular, the problem comes up for programs that make:

  • concurrent operations on multiple channels that operate on overlapping regions of a file

  • where at least one of the overlapping channels is a writing channel

  • and where data could be stored in more than one of the overlapping channel’s buffers at the same time (i.e., write and read ordering are not enforced through channel.flush and other means such as sync variables).

Note that it is possible in some cases to create a file that does not allow multiple channels at different offsets. Channels created on such files will not change the file’s position based on a start= offset arguments. Instead, each read or write operation will use the file descriptor’s current position. Therefore, only one channel should be created for files created in the following situations:

  • with openfp

  • with openfd when provided a non-seekable system file descriptor

Performing I/O with Channels

Channels contain read and write methods, which are generic methods that can read or write anything, and can also take optional arguments such as I/O style or. These functions generally take any number of arguments and throw if there was an error. See:

In addition, there is a convenient synonym for channel.write and channel.read: the <~> operator

Warning

the <~> operator is deprecated

Sometimes it’s important to flush the buffer in a channel - to do that, use the channel.flush() method. Flushing the buffer will make all writes available to other applications or other views of the file (e.g., it will call the OS call pwrite()). It is also possible to close a channel, which will implicitly flush it and release any buffer memory used by the channel. Note that if you need to ensure that data from a channel is on disk, you’ll have to call channel.flush or channel.close and then file.fsync on the related file.

Functions for Closing Channels

A channel must be closed in order to free the resources allocated for it, to ensure that data written to it is visible to other channels, or to allow the associated file to be closed.

See channel.close.

It is an error to perform any I/O operations on a channel that has been closed. It is an error to close a file when it has channels that have not been closed.

Files and channels are reference counted. Each file and channel is closed automatically when no references to it remain. For example, if a local variable is the only reference to a channel, the channel will be closed when that variable goes out of scope. Programs may also close a file or channel explicitly.

The stdin, stdout, and stderr Channels

Chapel provides the predefined channels stdin, stdout, and stderr to access the corresponding operating system streams standard input, standard output, and standard error.

stdin supports reading; stdout and stderr support writing.

All three channels are safe to use concurrently. Their types’ kind argument is dynamic.

Error Handling

Most I/O routines throw a OS.SystemError, and can be handled appropriately with try and catch.

Some of these subclasses commonly used within the I/O implementation include:

An error code can be converted to a string using the function OS.errorToString().

Ensuring Successful I/O

It is possible - in some situations - for I/O to fail without returning an error. In cases where a programmer wants to be sure that there was no error writing the data to disk, it is important to call file.fsync to make sure that data has arrived on disk without an error. Many errors can be reported with a typical operation, but some errors can only be reported by the system during file.close or even file.fsync.

When a file (or channel) is closed, data written to that file will be written to disk eventually by the operating system. If an application needs to be sure that the data is immediately written to persistent storage, it should use file.fsync prior to closing the file.

Correspondence with C I/O

It is not possible to seek, read, or write to a file directly; channels must be created and used.

channel.flush in Chapel has the same conceptual meaning as fflush() in C. However, fflush() is not necessarily called in channel.flush(), unlike fsync(), which is actually called by file.fsync() in Chapel.

IO Functions and Types

enum iomode { r = 1, cw = 2, rw = 3, cwr = 4 }

The iomode type is an enum. When used as arguments when opening files, its constants have the same meaning as the following strings passed to fopen() in C:

iomode

fopen() argument

Description

iomode.r

"r"

open an existing file for reading.

iomode.rw

"r+"

open an existing file for reading and writing.

iomode.cw

"w"

create a new file for writing. If the file already exists, its contents are truncated.

iomode.cwr

"w+"

same as iomode.cw, but reading from the file is also allowed.

However, open() in Chapel does not necessarily invoke fopen() in C.

enum iokind { dynamic = 0, native = 1, big = 2, little = 3 }

The iokind type is an enum. When used as arguments to the channel type, its constants have the following meaning:

  • iokind.dynamic means that the applicable I/O style has full effect and as a result the kind varies at runtime.

  • iokind.native means binary I/O in native byte order (similar to iokind.big but with the byte order that is native to the target platform).

  • iokind.big means binary I/O with big-endian byte order is performed when writing/reading basic types from the channel.

  • iokind.little means binary I/O with little-endian byte order (similar to iokind.big but with little-endian byte order).

In the case of iokind.big, iokind.little, and iokind.native the applicable iostyle is consulted when writing/reading strings, but not for other basic types.

There are synonyms available for these values:

param iodynamic = iokind.dynamic

A synonym for iokind.dynamic; see iokind

param ionative = iokind.native

A synonym for iokind.native; see iokind

param iobig = iokind.big

A synonym for iokind.big; see iokind

param iolittle = iokind.little

A synonym for iokind.little; see iokind

enum ioendian { native = 0, big = 1, little = 2 }

The ioendian type is an enum. When used as an argument to the channel methods, its constants have the following meanings:

  • ioendian.big means binary I/O is performed in big-endian byte order.

  • ioendian.little means binary I/O is performed in little-endian byte order.

  • ioendian.native means binary I/O is performed in the byte order that is native to the target platform.

enum iostringstyle { len1b_data = -1, len2b_data = -2, len4b_data = -4, len8b_data = -8, lenVb_data = -10, data_toeof = -0xff00, data_null = -0x0100 }

This enum contains values used to control binary I/O with strings via the str_style field in iostyle.

  • iostringstyle.len1b_data indicates a string format of 1 byte of length followed by length bytes of string data.

  • iostringstyle.len2b_data indicates a string format of 2 bytes of length followed by length bytes of string data.

  • iostringstyle.len4b_data indicates a string format of 4 bytes of length followed by length bytes of string data.

  • iostringstyle.len8b_data indicates a string format of 8 bytes of length followed by length bytes of string data.

  • iostringstyle.lenVb_data indicates a string format of a variable number of bytes of length, encoded with high-bit meaning more bytes of length follow, and where the 7-bits of length from each byte store the 7-bit portions of the length in order from least-significant to most-significant. This way of encoding a variable-byte length matches Google Protocol Buffers.

  • iostringstyle.data_toeof indicates a string format that contains only the string data without any length or terminator. When reading, this format will read a string until the end of the file is reached.

  • iostringstyle.data_null indicates a string that is terminated by a zero byte. It can be combined with other numeric values to indicate a string terminated by a particular byte. For example, to indicate a string terminated by $ (which in ASCII has byte value 0x24), one would use the value iostringstyle.data_null|0x24.

  • A positive and nonzero value indicates that a string of exactly that many bytes should be read or written.

enum iostringformat { word = 0, basic = 1, chpl = 2, json = 3, toend = 4, toeof = 5 }

This enum contains values used to control text I/O with strings via the string_format field in iostyle.

  • iostringformat.word means string is as-is; reading reads until whitespace. This is the default.

  • iostringformat.basic means only escape string_end and \ with \

  • iostringformat.chpl means escape string_end \ ' " \n with \ and nonprinting characters c = 0xXY with \xXY

  • iostringformat.json means escape string_end " and \ with \, and nonprinting characters c = \uABCD

  • iostringformat.toend means string is as-is; reading reads until string_end

  • iostringformat.toeof means string is as-is; reading reads until end of file

proc stringStyleTerminated(terminator: uint(8))

This method returns the appropriate iostyle str_style value to indicate a string format where strings are terminated by a particular byte.

Arguments

terminator – a byte value that the strings will be terminated by

Returns

a value that indicates a string format where strings are terminated by the terminator byte. This value is appropriate to store in iostyle.str_style.

Warning

stringStyleTerminated is unstable because it supports the unstable type ‘iostyle’

proc stringStyleNullTerminated()

This method returns the appropriate iostyle str_style value to indicate a string format where strings are terminated by a zero byte.

Warning

stringStyleNullTerminated is unstable because it supports the unstable type ‘iostyle’

proc stringStyleWithLength(lengthBytes: int) throws

Return the appropriate iostyle str_style value to indicate a string format where string data is preceded by a lengthBytes of length. Only lengths of 1, 2, 4, or 8 are supported. When lengthBytes is 0, the returned value indicates variable-byte length.

Throws

SystemError – Thrown for an unsupported value of lengthBytes.

Warning

stringStyleWithLength is unstable because it supports the unstable type ‘iostyle’

const IOHINT_NONE = 0: c_int

IOHINT_NONE means normal operation, nothing special to hint. Expect to use NONE most of the time. The other hints can be bitwise-ORed in.

Warning

‘IOHINT_NONE’ is deprecated; please use ‘ioHintSet.empty’ instead

const IOHINT_RANDOM = QIO_HINT_RANDOM

IOHINT_RANDOM means we expect random access to a file

Warning

‘IOHINT_RANDOM’ is deprecated; please use ‘ioHintSet.random’ instead

const IOHINT_SEQUENTIAL = QIO_HINT_SEQUENTIAL

IOHINT_SEQUENTIAL means expect sequential access. On Linux, this should double the readahead.

Warning

‘IOHINT_SEQUENTIAL’ is deprecated; please use ‘ioHintSet.sequential’ instead

const IOHINT_CACHED = QIO_HINT_CACHED

IOHINT_CACHED means we expect the entire file to be cached and/or we pull it in all at once. May request readahead on the entire file.

Warning

‘IOHINT_CACHED’ is deprecated; please use ‘ioHintSet.prefetch’ instead

const IOHINT_PARALLEL = QIO_HINT_PARALLEL

IOHINT_PARALLEL means that we expect to have many channels working with this file in parallel. It might change the reading/writing implementation to something more efficient in that scenario.

Warning

‘IOHINT_PARALLEL’ is deprecated

type iostyle = iostyleInternal

Warning

iostyle is unstable, a new way of controlling channel output is planned

proc defaultIOStyle(): iostyle
Returns

the default I/O style. See iostyle and I/O Styles

Warning

defaultIOStyle is unstable due to returning an unstable type

type iohints = c_int

Warning

the ‘iohints’ type is deprecated; please use the ‘ioHintSet’ type instead.

record ioHintSet

A value of the ioHintSet type defines a set of hints about the I/O that the file or channel will perform. These hints may be used by the implementation to select optimized versions of the I/O operations.

Most hints have POSIX equivalents associated with posix_fadvise() and posix_madvise().

use IO;

// define a set of hints using a union operation
var hints = ioHintSet::sequential | ioHintSet::prefetch;

// open a file using the hints
var f: file;
try! {
  f = open("path/to/my/file.txt", iomode.r, hints=hints);
}
proc type empty

Defines an empty set, which provides no hints. Corresponds to ‘POSIX_*_NORMAL’.

proc type sequential

Suggests that the file will be accessed sequentially. Corresponds to ‘POSIX_*_SEQUENTIAL’

proc type random

Suggests that the file will be accessed randomly. Corresponds to ‘POSIX_*_RANDOM’.

proc type prefetch

Suggests that the runtime/OS should immediately begin prefetching the file contents. Corresponds to ‘POSIX_*_WILLNEED’.

proc type mmap

Suggests that ‘mmap’ should be used to access the file contents

proc type noMmap

Suggests that ‘mmap’ should not be used to access the file contents. Instead, pread/pwrite are used.

operator ioHintSet.|(lhs: ioHintSet, rhs: ioHintSet)

Compute the union of two ioHintSets

operator ioHintSet.&(lhs: ioHintSet, rhs: ioHintSet)

Compute the intersection of two ioHintSets

operator ioHintSet.==(lhs: ioHintSet, rhs: ioHintSet)

Compare two ioHintSets for equality

operator ioHintSet.!=(lhs: ioHintSet, rhs: ioHintSet)

Compare two ioHintSets for inequality

record file

The file type is implementation-defined. A value of the file type refers to the state that is used by the implementation to identify and interact with the OS file.

When a file formal argument has default intent, the actual is passed by const ref to the formal upon a function call, and the formal cannot be assigned within the function.

The default value of the file type does not represent any OS file. It is illegal to perform any I/O operations on the default value.

proc file.check() throws

Throw an error if this is not a valid representation of an OS file.

Throws

SystemError – Indicates that this does not represent an OS file.

proc file.close() throws

Close a file.

In order to free the resources allocated for a file, it must be closed using this method.

Closing a file does not guarantee immediate persistence of the performed updates, if any. In cases where immediate persistence is important, file.fsync should be used for that purpose prior to closing the file. In particular, even though closing the file might complete without errors, the data written might not persist in the event of a severe error like running out of storage space or power loss. See also Ensuring Successful I/O.

Files are automatically closed when the file variable goes out of scope and all channels using that file are closed. Programs may also explicitly close a file using this method.

It is an error to perform any I/O operations on a file that has been closed. It is an error to close a file when it has channels that have not been closed.

Throws

SystemError – Thrown if the file could not be closed.

proc file.fsync() throws

Sync a file to disk.

Commits file data to the device associated with this file. Data written to the file by a channel will only be guaranteed committed if the channel has been closed or flushed.

This function will typically call the fsync system call.

Throws

SystemError – Thrown if the file could not be synced.

proc file.path: string throws

Get the path to an open file.

Note that not all files have a path (e.g. files opened with openmem), and that this function may not work on all operating systems.

The function Path.realPath is an alternative way to get the path to a file.

Throws

SystemError – Thrown if the path could not be retrieved.

proc file.tryGetPath(): string

Get the path to an open file, or return “unknown” if there was a problem getting the path to the open file.

Warning

file.tryGetPath is deprecated

proc file.size: int throws

Get the current size of an open file. Note that the size can always change if other channels, tasks or programs are writing to the file.

Returns

the current file size

Throws

SystemError – Thrown if the size could not be retrieved.

proc open(path: string, mode: iomode, hints: iohints, style: iostyle): file throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘open’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc open(path: string, mode: iomode, hints = ioHintSet.empty, style: iostyle): file throws

Warning

open with a style argument is unstable

proc open(path: string, mode: iomode, hints = ioHintSet.empty): file throws

Open a file on a filesystem. Note that once the file is open, you will need to use a file.reader or file.writer to create a channel to actually perform I/O operations

Arguments

  • path – which file to open (for example, “some/file.txt”).

  • mode – specify whether to open the file for reading or writing and whether or not to create the file if it doesn’t exist. See iomode.

  • hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file to the requested resource.

Throws

SystemError – Thrown if the file could not be opened.

proc open(path: string, mode: iomode, hints: iohints = IOHINT_NONE): file throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘open’ that takes an ‘ioHintSet’ instead.

proc openfd(fd: fd_t, hints: iohints, style: iostyle): file throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘openfd’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc openfd(fd: fd_t, hints = ioHintSet.empty, style: iostyle): file throws

Warning

openfd with a style argument is unstable

proc openfd(fd: fd_t, hints = ioHintSet.empty): file throws

Create a Chapel file that works with a system file descriptor. Note that once the file is open, you will need to use a file.reader or file.writer to create a channel to actually perform I/O operations

The system file descriptor will be closed when the Chapel file is closed.

Note

This function can be used to create Chapel files that refer to system file descriptors that do not support the seek functionality. For example, file descriptors that represent pipes or open socket connections have this property. In that case, the resulting file value should only be used with one channel at a time. The I/O system will ignore the channel offsets when reading or writing to files backed by non-seekable file descriptors.

Arguments

  • fd – a system file descriptor.

  • hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file using the specified file descriptor.

Throws

SystemError – Thrown if the file descriptor could not be retrieved.

proc openfd(fd: fd_t, hints: iohints = IOHINT_NONE): file throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘openfd’ that takes an ‘ioHintSet’ instead.

proc openfp(fp: _file, hints: iohints, style: iostyle): file throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘openfp’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc openfp(fp: _file, hints = ioHintSet.empty, style: iostyle): file throws

Warning

openfp with a style argument is unstable

proc openfp(fp: _file, hints = ioHintSet.empty): file throws

Create a Chapel file that works with an open C file (ie a FILE*). Note that once the file is open, you will need to use a file.reader or file.writer to create a channel to actually perform I/O operations

Note

The resulting file value should only be used with one channel at a time. The I/O system will ignore the channel offsets when reading or writing to a file opened with openfp.

Arguments

  • fp – a C FILE* to work with

  • hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open file that uses the underlying FILE* argument.

Throws

SystemError – Thrown if the C file could not be retrieved.

proc openfp(fp: _file, hints: iohints = IOHINT_NONE): file throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘openfp’ that takes an ‘ioHintSet’ instead.

proc opentmp(hints: iohints, style: iostyle): file throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘opentmp’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc opentmp(hints = ioHintSet.empty, style: iostyle): file throws

Warning

opentmp with a style argument is unstable

proc opentmp(hints = ioHintSet.empty): file throws

Open a temporary file. Note that once the file is open, you will need to use a file.reader or file.writer to create a channel to actually perform I/O operations.

The temporary file will be created in an OS-dependent temporary directory, for example “/tmp” is the typical location. The temporary file will be deleted upon closing.

Temporary files are always opened with iomode iomode.cwr; that is, a new file is created that supports both writing and reading.

Arguments

hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open temporary file.

Throws

SystemError – Thrown if the temporary file could not be opened.

proc opentmp(hints: iohints = IOHINT_NONE): file throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘opentmp’ that takes an ‘ioHintSet’ instead.

proc openmem(style: iostyle): file throws

Warning

openmem with a style argument is unstable

proc openmem(): file throws

Open a file that is backed by a buffer in memory that will not persist when the file is closed. Note that once the file is open, you will need to use a file.reader or file.writer to create a channel to actually perform I/O operations.

The resulting file supports both reading and writing.

Returns

an open memory file.

Throws

SystemError – Thrown if the memory buffered file could not be opened.

record channel

A channel supports either sequential reading or sequential writing to an underlying file object. A channel can buffer data. Read operations on the channel might return old data. Write operations might not have an immediate effect. Use channel.flush to control this buffering.

The channel type is implementation-defined. A value of the channel type refers to the state that is used to implement the channel operations.

When a channel formal argument has default intent, the actual is passed by const ref to the formal upon a function call, and the formal cannot be assigned within the function.

The default value of the channel type is not associated with any file, and so cannot be used to perform I/O.

The channel type is generic.

param writing: bool

writing is a boolean indicating whether the channels of this type support writing (when true) or reading (when false).

param kind: iokind

kind is an enum iokind that allows narrowing this channel’s I/O style for more efficient binary I/O.

param locking: bool

locking is a boolean indicating whether it is safe to use this channel concurrently (when true).

proc channel.init=(x: channel)
record ioChar

Represents a Unicode codepoint. I/O routines (such as channel.read and channel.write) can use arguments of this type in order to read or write a single Unicode codepoint.

var ch: int(32)

The codepoint value

record ioNewline

Represents a newline character or character sequence (ie \n). I/O routines (such as channel.read and channel.write) can use arguments of this type in order to read or write a newline. This is different from \n because an ioNewline always produces an actual newline, but in some cases writing \n will produce an escaped string (such as "\n").

When reading an ioNewline, read routines will skip any character sequence (including, e.g., letters and numbers) to get to the newline character unless skipWhitespaceOnly is set to true.

var skipWhitespaceOnly: bool = false

Normally, we will skip anything at all to get to a \n, but if skipWhitespaceOnly is set, it will be an error if we run into non-space characters other than \n.

record ioLiteral

Used to represent a constant string we want to read or write.

When writing, the ioLiteral is output without any quoting or escaping.

When reading, the ioLiteral must be matched exactly - or else the read call will return an error with code SysBasic.EFORMAT.

var val: string

The value of the literal

var ignoreWhiteSpace: bool = true

Should read operations using this literal ignore and consume whitespace before the literal?

proc writeThis(f) throws
record ioBits

Represents a value with a particular bit length that we want to read or write. The I/O will always be done in binary mode.

var v: uint(64)

The bottom nbits of v will be read or written

var nbits: int(8)

How many of the low-order bits of v should we read or write?

proc channel.lock() throws

Acquire a channel’s lock.

Throws

SystemError – Thrown if the lock could not be acquired.

proc channel.unlock()

Release a channel’s lock.

proc channel.offset(): int(64)

Return the current offset of a channel.

Warning

If the channel can be used by multiple tasks, take care when doing operations that rely on the channel’s current offset. To prevent race conditions, first lock the channel with channel.lock, do the operations with channel._offset instead, then unlock it with channel.unlock.

Returns

the current offset of the channel

proc channel.advance(amount: int(64)) throws

Move a channel offset forward.

For a reading channel, this function will consume the next amount bytes. If EOF is reached, the channel position may be left at the EOF.

For a writing channel, this function will write amount zeros - or some other data if it is stored in the channel’s buffer, for example with channel._mark and channel._revert.

Throws

SystemError – Throws if the channel offset was not moved.

proc channel.advancePastByte(byte: uint(8)) throws

Reads until byte is found and then leave the channel offset just after it.

Throws

  • EofError – if the requested byte could not be found.

  • SystemError – if another error occurred.

proc channel.mark() throws

Mark a channel - that is, save the current offset of the channel on its mark stack. This function can only be called on a channel with locking==false.

The mark stack stores several channel offsets. For any channel offset that is between the minimum and maximum value in the mark stack, I/O operations on the channel will keep that region of the file buffered in memory so that those operations can be undone. As a result, it is possible to perform I/O transactions on a channel. The basic steps for an I/O transaction are:

  • mark the current position with channel.mark

  • do something speculative (e.g. try to read 200 bytes of anything followed by a ‘B’)

  • if the speculative operation was successful, commit the changes by calling channel.commit

  • if the speculative operation was not successful, go back to the mark by calling channel.revert. Subsequent I/O operations will work as though nothing happened.

Note

Note that it is possible to request an entire file be buffered in memory using this feature, for example by marking at offset=0 and then advancing to the end of the file. It is important to be aware of these memory space requirements.

Returns

The offset that was marked

Throws

SystemError: if marking the channel failed

proc channel.revert()

Abort an I/O transaction. See channel.mark. This function will pop the last element from the mark stack and then leave the previous channel offset unchanged. This function can only be called on a channel with locking==false.

proc channel.commit()

Commit an I/O transaction. See channel.mark. This function will pop the last element from the mark stack and then set the channel offset to the popped offset. This function can only be called on a channel with locking==false.

proc channel.seek(start: int(64), end: int(64) = max(int(64))) throws

Warning

channel.seek with a start and/or end argument is deprecated. Please use the new region argument instead

proc channel.seek(region: range(?)) throws

Reset a channel to point to a new part of a file. This function allows one to jump to a different part of a file without creating a new channel. It can only be called on a channel with locking==false.

The region specified must have a lower bound, but does not need to have a high bound for correctness. Specifying the high bound might be an important performance optimization since the channel will not try to read data outside of the region.

This function will, in most cases, discard the channel’s buffer. When writing, the data will be saved to the file before discarding.

Arguments

region – the new region, measured in bytes and counting from 0

Warning

The region argument will ignore any specified stride other than 1.

Throws

  • SystemError – if seeking failed. Possible reasons include that the file is not seekable, or that the channel is marked.

  • IllegalArgumentError – if region argument did not have a lower bound

proc channel._offset(): int(64)

For a channel locked with channel.lock, return the offset of that channel.

proc channel._mark() throws

This routine is identical to channel.mark except that it can be called on channels with locking==true and should be called only once the channel has been locked with channel.lock. The channel should not be unlocked with channel.unlock until after the mark has been committed with channel._commit or reverted with channel._revert.

See channel.mark for details other than the locking discipline.

Returns

The offset that was marked

Throws

SystemError: if marking the channel failed

proc channel._revert()

Abort an I/O transaction. See channel._mark. This function will pop the last element from the mark stack and then leave the previous channel offset unchanged. This function should only be called on a channel that has already been locked and marked.

proc channel._commit()

Commit an I/O transaction. See channel._mark. This function will pop the last element from the mark stack and then set the channel offset to the popped offset. This function should only be called on a channel that has already been locked and marked.

proc channel._style(): iostyle

Return the current style used by a channel. This function should only be called on a locked channel.

Warning

channel._style is unstable because it returns a type that is unstable

proc channel._set_style(style: iostyle)

Set the style associated with a channel. This function should only be called on a locked channel.

Warning

channel._set_style is unstable because its purpose involves an unstable type

proc channel.readWriteThisFromLocale()

Return the locale on which an ongoing I/O was started with a channel. This method will return nilLocale unless it is called on a channel that is the formal argument to a readThis or writeThis method.

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints, style: iostyle): channel(false, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘openreader’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): channel(false, kind, locking) throws

Warning

openreader with a style argument is unstable

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty): channel(false, kind, locking) throws

Warning

openreader with a start and/or end argument is deprecated. Please use the new region argument instead

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): channel(false, kind, locking) throws

Open a file at a particular path and return a reading channel for it. This function is equivalent to calling open and then file.reader on the resulting file.

Arguments

  • path – which file to open (for example, “some/file.txt”).

  • kind – iokind compile-time argument to determine the corresponding parameter of the channel type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.

  • locking – compile-time argument to determine whether or not the channel should use locking; sets the corresponding parameter of the channel type. Defaults to true, but when safe, setting it to false can improve performance.

  • region – zero-based byte offset indicating where in the file the channel should start and stop reading. Defaults to 0.., meaning from the start of the file to no specified end point.

  • hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open reading channel to the requested resource.

Warning

The region argument will ignore any specified stride other than 1.

Throws

  • SystemError – Thrown if a reading channel could not be returned.

  • IllegalArgumentError – Thrown if trying to read explicitly prior to byte 0.

proc openreader(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints): channel(false, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘openreader’ that takes an ‘ioHintSet’ instead.

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints, style: iostyle): channel(true, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘openwriter’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty): channel(true, kind, locking) throws

Warning

openwriter with a start and/or end argument is deprecated.

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): channel(true, kind, locking) throws

Warning

openwriter with a style argument is unstable

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, hints = ioHintSet.empty): channel(true, kind, locking) throws

Open a file at a particular path and return a writing channel for it. This function is equivalent to calling open with iomode.cwr and then file.writer on the resulting file.

Arguments

  • path – which file to open (for example, “some/file.txt”).

  • kind – iokind compile-time argument to determine the corresponding parameter of the channel type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.

  • locking – compile-time argument to determine whether or not the channel should use locking; sets the corresponding parameter of the channel type. Defaults to true, but when safe, setting it to false can improve performance.

  • hints – optional argument to specify any hints to the I/O system about this file. See ioHintSet.

Returns

an open writing channel to the requested resource.

Throws

SystemError – Thrown if a writing channel could not be returned.

proc openwriter(path: string, param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints): channel(true, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘openwriter’ that takes an ‘ioHintSet’ instead.

proc file.reader(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints, style: iostyle): channel(false, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘file.reader’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc file.reader(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): channel(false, kind, locking) throws

Warning

reader with a style argument is unstable

proc file.reader(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty): channel(false, kind, locking) throws

Warning

file.reader with a start and/or end argument is deprecated. Please use the new region argument instead

proc file.reader(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): channel(false, kind, locking) throws

Create a channel that supports reading from a file. See I/O Overview.

The start= and end= arguments define the region of the file that the channel will read from. These are byte offsets; the beginning of the file is at the offset 0. The defaults for these arguments enable the channel to access the entire file.

A channel will never read beyond its maximum end position. In addition, reading from a channel beyond the end of the underlying file will not extend that file. Reading beyond the end of the file or beyond the end offset of the channel will produce the error EEOF (and return false in many cases such as channel.read) to indicate that the end was reached.

Arguments

  • kind – iokind compile-time argument to determine the corresponding parameter of the channel type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.

  • locking – compile-time argument to determine whether or not the channel should use locking; sets the corresponding parameter of the channel type. Defaults to true, but when safe, setting it to false can improve performance.

  • region – zero-based byte offset indicating where in the file the channel should start and stop reading. Defaults to 0.. - meaning from the start of the file to no end point.

  • hints – provide hints about the I/O that this channel will perform. See ioHintSet. The default value of ioHintSet.empty will cause the channel to use the hints provided when the file was opened.

Warning

The region argument will ignore any specified stride other than 1.

Throws

  • SystemError – Thrown if a file reader channel could not be returned.

  • IllegalArgumentError – Thrown if trying to read explicitly prior to byte 0.

proc file.reader(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints): channel(false, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘file.reader’ that takes an ‘ioHintSet’ instead.

proc file.lines(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints, in local_style: iostyle) throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘file.lines’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc file.lines(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, in local_style: iostyle) throws

Warning

lines with a local_style argument is unstable

proc file.lines(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty) throws

Warning

file.lines with a start and/or end argument is deprecated. Please use the new region argument instead

proc file.lines(param locking: bool = true, region: range(?) = 0.., hints = ioHintSet.empty) throws

Iterate over all of the lines in a file.

Returns

an object which yields strings read from the file

Throws

SystemError – Thrown if an object could not be returned.

proc file.lines(param locking: bool = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints) throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘file.lines’ that takes an ‘ioHintSet’ instead.

proc file.writer(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints, style: iostyle): channel(true, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use the unstable variant of ‘file.writer’ that takes an ‘ioHintSet’ and an ‘iostyle’ instead.

proc file.writer(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty, style: iostyle): channel(true, kind, locking) throws

Warning

writer with a style argument is unstable

proc file.writer(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints = ioHintSet.empty): channel(true, kind, locking) throws

Warning

file.writer with a start and/or end argument is deprecated. Please use the new region argument instead

proc file.writer(param kind = iokind.dynamic, param locking = true, region: range(?) = 0.., hints = ioHintSet.empty): channel(true, kind, locking) throws

Create a channel that supports writing to a file. See I/O Overview.

The start= and end= arguments define the region of the file that the channel will write to. These are byte offsets; the beginning of the file is at the offset 0. The defaults for these arguments enable the channel to access the entire file.

When a channel writes to a file, it will replace file data that was previously stored at the relevant offset. If the offset is beyond the end of the file, the file will be extended.

A channel will never write beyond its maximum end position. It will extend the file only as necessary to store data written to the channel. In other words, specifying end here does not impact the file size directly; it impacts only the section of the file that this channel can write to. After all channels to a file are closed, that file will have a size equal to the last position written to by any channel.

Arguments

  • kind – iokind compile-time argument to determine the corresponding parameter of the channel type. Defaults to iokind.dynamic, meaning that the associated iostyle controls the formatting choices.

  • locking – compile-time argument to determine whether or not the channel should use locking; sets the corresponding parameter of the channel type. Defaults to true, but when safe, setting it to false can improve performance.

  • region – zero-based byte offset indicating where in the file the channel should start and stop writing. Defaults to 0.. - meaning from the start of the file to no specified end point.

  • hints – provide hints about the I/O that this channel will perform. See ioHintSet. The default value of ioHintSet.empty will cause the channel to use the hints provided when the file was opened.

Warning

The region argument will ignore any specified stride other than 1.

Throws

  • SystemError – Thrown if a file writer channel could not be returned.

  • IllegalArgumentError – Thrown if trying to write explicitly prior to byte 0.

proc file.writer(param kind = iokind.dynamic, param locking = true, start: int(64) = 0, end: int(64) = max(int(64)), hints: iohints): channel(true, kind, locking) throws

Warning

The ‘iohints’ type is deprecated; please use a variant of ‘file.writer’ that takes an ‘ioHintSet’ instead.

operator channel.<~>(const ref ch: channel, const x) const ref throws

The <~> operator

This <~> operator invokes readThis or writeThis with x, depending on the type of channel. This operator returns a const reference to the same channel so that multiple operator calls can be chained together.

Warning

The <~> operator on channels is deprecated. The intended alternative is to use methods like channel.read and channel.write instead.

The chaining functionality supported by this operator is not provided by other methods.

Returns

ch

Throws

SystemError – When an IO error has occurred.

operator channel.<~>(const ref r: channel, lit: ioLiteral) const ref throws

Overload to support reading an IO.ioLiteral without passing ioLiterals by reference, so that

reader <~> new ioLiteral("=")

works without requiring an explicit temporary value to store the ioLiteral.

Warning

The <~> operator on channels is deprecated. The intended alternative is to use methods like channel.readLiteral and channel.writeLiteral instead.

The chaining functionality supported by this operator is not provided by other methods.

operator channel.<~>(const ref r: channel, nl: ioNewline) const ref throws

Overload to support reading an IO.ioNewline without passing ioNewline by reference, so that

reader <~> new ioNewline()

works without requiring an explicit temporary value to store the ioNewline.

Warning

The <~> operator on channels is deprecated. The intended alternative is to use methods like channel.readNewline and channel.writeNewline instead.

The chaining functionality supported by this operator is not provided by other methods.

proc channel.readWriteLiteral(lit: string, ignoreWhiteSpace = true) throws

Explicit call for reading or writing a literal as an alternative to using IO.ioLiteral.

proc channel.readLiteral(literal: string, ignoreWhitespace = true): void throws

Advances the position of a channel by reading the exact text of the given string literal from the channel.

If the string is not matched exactly, then the channel’s position is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the channel is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

  • literal – the string to be matched.

  • ignoreWhitespace – determines whether leading whitespace is ignored.

Throws

  • BadFormatError – Thrown if literal could not be matched.

  • EofError – Thrown if end of channel is encountered.

Warning

channel.readLiteral is unstable and subject to change.

proc channel.readLiteral(literal: bytes, ignoreWhitespace = true): void throws

Advances the position of a channel by reading the exact bytes of the given literal from the channel.

If the bytes are not matched exactly, then the channel’s position is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the channel is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

  • literal – the bytes to be matched.

  • ignoreWhitespace – determines whether leading whitespace is ignored.

Throws

  • BadFormatError – Thrown if literal could not be matched.

  • EofError – Thrown if end of channel is encountered.

Warning

channel.readLiteral is unstable and subject to change.

proc channel.readNewline(): void throws

Advances the position of the channel by reading a newline.

If a newline is not matched exactly, then the channel’s position is unchanged. In such cases a OS.BadFormatError will be thrown, unless the end of the channel is encountered in which case an OS.EofError will be thrown. By default this method will ignore leading whitespace when attempting to read a newline.

Throws

  • BadFormatError – Thrown if a newline could not be matched.

  • EofError – Thrown if end of channel is encountered.

Warning

channel.readNewline is unstable and subject to change.

proc channel.matchLiteral(literal: string, ignoreWhitespace = true): bool throws

Advances the position of a channel by reading the exact text of the given string literal from the channel.

If the string is not matched exactly, then the channel’s position is unchanged and this method will return false. In other words, this channel will return false in the cases where channel.readLiteral would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

  • literal – the string to be matched.

  • ignoreWhitespace – determines whether leading whitespace is ignored.

Returns

true if the read succeeded, and false on end of file or if the literal could not be matched.

Warning

channel.matchLiteral is unstable and subject to change.

proc channel.matchLiteral(literal: bytes, ignoreWhitespace = true): bool throws

Advances the position of a channel by reading the exact bytes of the given literal from the channel.

If the bytes are not matched exactly, then the channel’s position is unchanged and this method will return false. In other words, this channel will return false in the cases where channel.readLiteral would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a literal.

Arguments

  • literal – the bytes to be matched.

  • ignoreWhitespace – determines whether leading whitespace is ignored.

Returns

true if the read succeeded, and false on end of file or if the literal could not be matched.

Warning

channel.matchLiteral is unstable and subject to change.

proc channel.matchNewline(): bool throws

Advances the position of the channel by reading a newline.

If a newline is not matched exactly, then the channel’s position is unchanged and this method will return false. In other words, this channel will return false in the cases where channel.readNewline would throw a OS.BadFormatError or an OS.EofError.

By default this method will ignore leading whitespace when attempting to read a newline.

Returns

true if the read succeeded, and false on end of file or if the newline could not be matched.

Warning

channel.matchNewline is unstable and subject to change.

proc channel.writeLiteral(literal: string): void throws

Writes a string to the channel, ignoring any formatting configured for this channel.

Warning

channel.writeLiteral is unstable and subject to change.

proc channel.writeLiteral(literal: bytes): void throws

Writes bytes to the channel, ignoring any formatting configured for this channel.

Warning

channel.writeLiteral is unstable and subject to change.

proc channel.writeNewline(): void throws

Writes a newline to the channel, ignoring any formatting configured for this channel.

Warning

channel.writeNewline is unstable and subject to change.

proc channel.readWriteNewline() throws

Explicit call for reading or writing a newline as an alternative to using IO.ioNewline.

proc channel.binary(): bool

Returns true if this channel is configured for binary I/O.

proc channel.writeBytes(x, len: c_ssize_t): bool throws

Write a sequence of bytes.

Throws

SystemError – Thrown if the byte sequence could not be written.

iter channel.lines()

Iterate over all of the lines ending in \n in a channel - the channel lock will be held while iterating over the lines.

Only serial iteration is supported.

Warning

This iterator executes on the current locale. This may impact multilocale performance if the current locale is not the same locale on which the channel was created.

Yields

lines ending in \n in channel

proc stringify(const args ...?k): string

Creates a string representing the result of writing the arguments.

Writes each argument, possibly using a writeThis method, to a string and returns the result.

proc channel.read(ref args ...?k): bool throws

Read values from a channel. The input will be consumed atomically - the channel lock will be held while reading all of the passed values.

Arguments

args – a list of arguments to read. Basic types are handled internally, but for other types this function will call value.readThis() with a Reader argument as described in The readThis() and writeThis() Methods.

Returns

true if the read succeeded, and false on end of file.

Throws

SystemError – Thrown if the channel could not be read.

proc channel.read(ref args ...?k, style: iostyle): bool throws

Warning

read with a style argument is unstable

proc channel.readline(arg: [] uint(8), out numRead: int, start = arg.domain.lowBound, amount = arg.domain.highBound - start + 1): bool throws

Read a line into a Chapel array of bytes. Reads until a \n is reached. The \n is returned in the array.

Note that this routine currently requires a 1D rectangular non-strided array.

Throws a SystemError if a line could not be read from the channel.

Arguments

  • arg – A 1D DefaultRectangular array which must have at least 1 element.

  • numRead – The number of bytes read.

  • start – Index to begin reading into.

  • amount – The maximum amount of bytes to read.

Returns

true if the bytes were read without error.

Warning

channel.readline is deprecated. Use channel.readLine instead

proc channel.readLine(ref a: [] ?t, maxSize = a.size, stripNewline = false): int throws

Read a line into a Chapel array of bytes. Reads until a \n is reached. This function always does a binary read (i.e. it is not aware of UTF-8 etc) and is similar in some ways to readLine(bytes) but works with an array directly. However, it does not resize the array but rather stores up to first ‘size’ bytes in to it. The exact number of bytes in the array set will depend on the line length (and on stripNewline since the newline will be counted if it is stored in the array).

Arguments

  • a – A 1D DefaultRectangular non-strided array storing int(8) or uint(8) which must have at least 1 element.

  • maxSize – The maximum number of bytes to store into the a array. Defaults to the size of the array.

  • stripNewline – Whether to strip the trailing \n from the line.

Returns

Returns 0 if EOF is reached and no data is read. Otherwise, returns the number of array elements that were set by this call.

Throws

  • SystemError – Thrown if data could not be read from the channel.

  • IoError – Thrown if the line is longer than maxSize. It leaves the input marker at the beginning of the offending line.

proc channel.readline(ref arg: ?t): bool throws

Read a line into a Chapel string or bytes. Reads until a \n is reached. The \n is included in the resulting value.

Arguments

arg – a string or bytes to receive the line

Returns

true if a line was read without error, false upon EOF

Throws

SystemError – Thrown if data could not be read from the channel.

Warning

channel.readline is deprecated. Use channel.readLine instead

proc channel.readLine(ref s: string, maxSize = -1, stripNewline = false): bool throws

Read a line into a Chapel string. Reads until a \n is reached.

Arguments

  • s – a string to receive the line

  • maxSize – The maximum number of codepoints to store into s. The default of -1 means to read an unlimited number of codepoints.

  • stripNewline – Whether to strip the trailing \n from the line.

Returns

true if a line was read without error, false upon EOF

Throws

  • SystemError – Thrown if data could not be read from the channel.

  • IoError – Thrown if the line is longer than maxSize. It leaves the input marker at the beginning of the offending line.

proc channel.readLine(ref b: bytes, maxSize = -1, stripNewline = false): bool throws

Read a line into Chapel bytes. Reads until a \n is reached.

Arguments

  • b – bytes to receive the line

  • maxSize – The maximum number of bytes to store into b. The default of -1 means to read an unlimited number of bytes.

  • stripNewline – Whether to strip the trailing \n from the line.

Returns

true if a line was read without error, false upon EOF

Throws

  • SystemError – Thrown if data could not be read from the channel.

  • IoError – Thrown if the line is longer than maxSize. It leaves the input marker at the beginning of the offending line.

proc channel.readLine(type t = string, maxSize = -1, stripNewline = false): t throws

Read a line. Reads until a \n is reached.

Arguments

  • t – the type of data to read, which must be string or bytes. Defaults to string if not specified.

  • maxSize – The maximum number of codepoints to read. The default of -1 means to read an unlimited number of codepoints.

  • stripNewline – Whether to strip the trailing \n from the line.

Returns

The data that was read.

Throws

  • SystemError – Thrown if data could not be read from the channel.

  • IoError – Thrown if the line is longer than maxSize. It leaves the input marker at the beginning of the offending line.

proc channel.readstring(ref str_out: string, len: int(64) = -1): bool throws

read a given number of bytes from a channel

Arguments

  • str_out – The string to be read into

  • len – Read up to len bytes from the channel, up until EOF (or some kind of I/O error). If the default value of -1 is provided, read until EOF starting from the channel’s current offset.

Returns

true if we read something, false upon EOF

Throws

SystemError – Thrown if the bytes could not be read from the channel.

proc channel.readbytes(ref bytes_out: bytes, len: int(64) = -1): bool throws

read a given number of bytes from a channel

Arguments

  • bytes_out – The bytes to be read into

  • len – Read up to len bytes from the channel, up until EOF (or some kind of I/O error). If the default value of -1 is provided, read until EOF starting from the channel’s current offset.

Returns

true if we read something, false upon EOF

Throws

SystemError – Thrown if the bytes could not be read from the channel.

proc channel.readbits(ref v: integral, nbits: integral): bool throws

Read bits with binary I/O

Arguments

  • v – where to store the read bits. This value will have its nbits least-significant bits set.

  • nbits – how many bits to read

Returns

true if the bits were read without error, false upon EOF

Throws

SystemError – Thrown if the bits could not be read from the channel.

proc channel.writebits(v: integral, nbits: integral): bool throws

Write bits with binary I/O

Arguments

  • v – a value containing nbits bits to write the least-significant bits

  • nbits – how many bits to write

Returns

true if the bits were written without error, false on error

Throws

  • IllegalArgumentError – Thrown if writing more bits than fit into v.

  • SystemError – Thrown if the bits could not be written to the channel.

proc channel.writeBinary(arg: numeric, param endian: ioendian = ioendian.native) throws

Write a binary number to the channel

Arguments

  • arg – number to be written

  • endian – ioendian compile-time argument that specifies the byte order in which to write the number. Defaults to ioendian.native.

Throws

SystemError – Thrown if the number could not be written to the channel.

proc channel.writeBinary(arg: numeric, endian: ioendian) throws

Write a binary number to the channel

Arguments

  • arg – number to be written

  • endian – ioendian specifies the byte order in which to write the number.

Throws

SystemError – Thrown if the number could not be written to the channel.

proc channel.readBinary(ref arg: numeric, param endian: ioendian = ioendian.native): bool throws

Read a binary number from the channel

Arguments

  • arg – number to be read

  • endian – ioendian compile-time argument that specifies the byte order in which to read the number. Defaults to ioendian.native.

Returns

true if the number was read, false otherwise

Throws

SystemError – Thrown if an error occurred reading the number.

proc channel.readBinary(ref arg: numeric, endian: ioendian): bool throws

Read a binary number from the channel

Arguments

  • arg – number to be read

  • endian – ioendian specifies the byte order in which to read the number.

Returns

true if the number was read, false otherwise

Throws

SystemError – Thrown if an error occurred reading the number.

proc channel.readln(ref args ...?k): bool throws

Read values from a channel and then consume any bytes until newline is reached. The input will be consumed atomically - the channel lock will be held while reading all of the passed values.

Arguments

args – a list of arguments to read. This routine can be called with zero or more such arguments. Basic types are handled internally, but for other types this function will call value.readThis() with a Reader argument as described in The readThis() and writeThis() Methods.

Returns

true if the read succeeded, and false upon end of file.

Throws

SystemError – Thrown if a line could not be read from the channel.

proc channel.readln(ref args ...?k, style: iostyle): bool throws

Warning

readln with a style argument is unstable

proc channel.read(type t) throws

Read a value of passed type.

For example, the following line of code reads a value of type int from stdin and uses it to initialize a variable x:

var x = stdin.read(int)
Arguments

t – the type to read

Returns

the value read

Throws

SystemError – Thrown if the type could not be read from the channel.

proc channel.readln(type t) throws

Read a value of passed type followed by a newline.

Arguments

t – the type to read

Returns

the value read

Throws

SystemError – Thrown if the type could not be read from the channel.

proc channel.readln(type t ...?numTypes) throws

Read values of passed types followed by a newline and return a tuple containing the read values.

Arguments

t – more than one type to read

Returns

a tuple of the read values

Throws

SystemError – Thrown if the types could not be read from the channel.

proc channel.read(type t ...?numTypes) throws

Read values of passed types and return a tuple containing the read values.

Arguments

t – more than one type to read

Returns

a tuple of the read values

Throws

SystemError – Thrown if the types could not be read from the channel.

proc channel.write(const args ...?k): bool throws

Write values to a channel. The output will be produced atomically - the channel lock will be held while writing all of the passed values.

Arguments

args – a list of arguments to write. Basic types are handled internally, but for other types this function will call value.writeThis() with the channel as an argument.

Returns

true if the write succeeded

Throws

SystemError – Thrown if the values could not be written to the channel.

proc channel.write(const args ...?k, style: iostyle): bool throws

Warning

write with a style argument is unstable

proc channel.writeln(const args ...?k): bool throws

Write values to a channel followed by a newline. The output will be produced atomically - the channel lock will be held while writing all of the passed values.

Arguments

args – a variable number of arguments to write. This method can be called with zero or more arguments. Basic types are handled internally, but for other types this function will call value.writeThis() with the channel as an argument.

Returns

true if the write succeeded

Throws

SystemError – Thrown if the values could not be written to the channel.

proc channel.writeln(const args ...?k, style: iostyle): bool throws

Warning

writeln with a style argument is unstable

proc channel.flush() throws

Makes all writes to the channel, if any, available to concurrent viewers of its associated file, such as other channels or other applications accessing this file concurrently. Unlike file.fsync, this does not commit the written data to the file’s device.

Throws

SystemError – Thrown if the flush fails.

proc channel.assertEOF(errStr: string = "- Not at EOF")

Assert that a channel has reached end-of-file and that there was no error doing the read.

proc channel.close() throws

Close a channel. Implicitly performs the channel.flush operation (see Synchronization of Channel Data and Avoiding Data Races).

Throws

SystemError – Thrown if the channel is not successfully closed.

proc channel.isClosed(): bool

Return true if a channel is currently closed.

proc channel.isclosed(): bool

Warning

channel.isclosed is deprecated. Please use channel.isClosed instead

const stdin: channel(false, iokind.dynamic, true)

standard input, otherwise known as file descriptor 0

const stdout: channel(true, iokind.dynamic, true)

standard output, otherwise known as file descriptor 1

const stderr: channel(true, iokind.dynamic, true)

standard error, otherwise known as file descriptor 2

proc read(ref args ...?n): bool throws

Equivalent to stdin.read. See channel.read

proc read(type t ...?numTypes) throws

Equivalent to stdin.read. See channel.read for types

proc readLine(ref a: [] ?t, maxSize = a.size, stripNewline = false): int throws

Equivalent to stdin.readLine. See channel.readLine

proc readline(arg: [] uint(8), out numRead: int, start = arg.domain.lowBound, amount = arg.domain.highBound - start + 1): bool throws

Equivalent to stdin.readline. See channel.readline

Warning

readline is deprecated. Use readLine instead

proc readline(ref arg: ?t): bool throws

Equivalent to stdin.readline. See channel.readline

Warning

readline is deprecated. Use readLine instead

proc readLine(ref s: string, maxSize = -1, stripNewline = false): bool throws

Equivalent to stdin.readLine. See channel.readLine

proc readLine(ref b: bytes, maxSize = -1, stripNewline = false): bool throws

Equivalent to stdin.readLine. See channel.readLine

proc readLine(type t = string, maxSize = -1, stripNewline = false): t throws

Equivalent to stdin.readLine. See channel.readLine

proc readln(ref args ...?n): bool throws

Equivalent to stdin.readln. See channel.readln

proc readln(type t ...?numTypes) throws

Equivalent to stdin.readln. See channel.readln for types

Delete a file. This function is likely to be replaced by FileSystem.remove.

Arguments

path – the path to the file to remove

Throws

SystemError – Thrown if the file is not successfully deleted.

Warning

unlink is deprecated. Please use FileSystem.remove instead

proc unicodeSupported(): bool
Returns

true if this version of the Chapel runtime supports UTF-8 output.

proc file.getchunk(start: int(64) = 0, end: int(64) = max(int(64))): (int(64), int(64)) throws

Returns (chunk start, chunk end) for the first chunk in the file containing data in the region start..end-1. Note that the returned chunk might not cover all of the region in question.

Returns (0,0) if no such value exists.

Arguments

  • start – the file offset (starting from 0) where the region begins

  • end – the file offset just after the region

Returns

a tuple of (chunkStart, chunkEnd) so that the bytes in chunkStart..chunkEnd-1 are stored in a manner that makes reading that chunk at a time most efficient

Throws

SystemError – Thrown if the chunk is not attained.

Warning

file.getchunk is deprecated

proc file.localesForRegion(start: int(64), end: int(64))

Returns the ‘best’ locale to run something working with the region of the file in start..end-1.

This must return the same result when called from different locales. Returns a domain of locales that are “best” for the given region. If no locales are “best” we return a domain containing all locales.

Arguments

  • start – the file offset (starting from 0) where the region begins

  • end – the file offset just after the region

Returns

a set of locales that are best for working with this region

Return type

domain(locale)