file = cockpit.file(path,
                    { syntax: syntax_object,
                      binary: boolean,
                      max_read_size: int,
                      superuser: string,
                      host: string
                    })

promise = file.read()
promise
    .done(function (content, tag) { ... })
    .fail(function (error) { ... })

promise = file.replace(content, [ expected_tag ])
promise
    .done(function (new_tag) { ... })
    .fail(function (error) { ... })

promise = file.modify(callback, [ initial_content, initial_tag ]
promise
    .done(function (new_content, new_tag) { ... })
    .fail(function (error) { ... })

file.watch(function (content, tag, [error]) { })

file.close()

Simple reading and writing

You can read a file with code like this:

cockpit.file("/path/to/file").read()
    .done(function (content, tag) {
        ...
    })
    .fail(function (error) {
        ...
    });

The read() method returns a promise.

When successful, the promise will be resolved with the content of the file. Unless you specify options to change this (see below), the file is assumed to be text in the UTF-8 encoding, and content will be a string.

The tag that is passed to the done() callback is a short string that is associated with the file and changes whenever the content of the file changes. It is meant to be used with replace().

It is not an error when the file does not exist. In this case, the done() callback will be called with a null value for content and tag is "-".

The superuser and host options can be used the same way as described in the cockpit.channel() to provide a different access level to the file.

You can use the max_read_size option to limit the amount of data that is read. If the file is larger than the given limit, no data is read and the channel is closed with problem code too-large. The default limit is 16 MiB.

To write to a file, use code like this:

cockpit.file("/path/to/file").replace("my new content\n")
    .done(function (tag) {
        ...
    })
    .fail(function (error) {
        ...
    });

The replace() method returns a promise.

When the promise is resolved, the file has been atomically replaced (via the rename() syscall) with the new content. As with read(), by default the new content is a string and will be written to the file as UTF-8. The returned tag corresponds to the new content of the file.

When the promise is rejected because of an error, the file or its meta data has not been changed in any way.

As a special case, passing the value null to replace() will remove the file.

The replace() method can also check for conflicting changes to a file. You can pass a tag (as returned by read() or replace()) to replace(), and the file will only be replaced if it still has the given tag. If the tag of the file has changed, replace() will fail with an error object that has error.problem == "change-conflict". See modify() below for a convenient way to achieve transactional updates to a file.

File format

By default, a file is assumed to be text encoded in UTF-8, and the read() and replace() functions use strings to represent the content.

By specifying the syntax.parser() and syntax.stringify() options, you can cause read() to parse the content before passing it back to you, and replace() to unparse it before writing.

The main idea is to be able to write { syntax: JSON }, of course, but you can easily pass in individual functions or make your own parser/unparser object:

cockpit.file("/path/to/file.json", { syntax: JSON })

var syntax_object = {
    parse:     my_parser,
    stringify: my_unparser
};

cockpit.file("/path/to/file", { syntax: syntax_object })

Any exceptions thrown by the parse() and stringify() functions are caught and reported as read or write errors.

The null value that is used to represent the content of a non-existing file (see "Simple reading and writing", above) is not passed through the parse() and stringify() functions.

Binary files

By default the content of the file is assumed to be text encoded as UTF-8 and it can not contain zero bytes. The content is represented as a JavaScript string with read(), replace(), etc. By setting the binary option to true when creating the proxy, no assumptions are placed on the content, and it is represented as a Uint8Array in JavaScript.

Atomic modifications

Use modify() to modify the content of the file safely. A call to modify() will read the content of the file, call callback on the content, and then replace the content of the file with the return value of the callback.

The modify() method uses the read() and replace() methods internally in the obvious way. Thus, the syntax.parse() and syntax.stringify() options work as expected, null represents a non-existing file, and the watch callbacks are fired.

It will do this one or more times, until no other conflicting changes have been made to the file between reading and replacing it.

The callback is called like this

new_content = callback (old_content)

The callback is allowed to mutate old_content, but note that this will also mutate the objects that are passed to the watch callbacks. Returning undefined from the proxy is the same as returning old_content.

The modify() method returns a promise.

The promise will be resolved with the new content and its tag, like so

function shout(old_content) {
    return old_content.toUpperCase();
}

cockpit.file("/path/to/file").modify(shout)
    .done(function (content, tag) {
        ...
    })
    .fail(function (error) {
        ...
    });

If you have cached the last content and tag results of the read() or modify() method, or the last values passed to a watch callback, you can pass them to modify() as the second and third argument. In this case, modify() will skip the initial read and start with the given values.

Change notifications

Calling watch() will start monitoring the file for external changes.

handle = file.watch(callback);

Whenever a change occurs, the callback() is called with the new content and tag of the file. This might happen because of external changes, but also as part of calls to read(), replace(), and modify().

When a read error occurs, the callback() is called with an error as a third argument. Write errors are not reported via the watch callback.

Calling watch() will also automatically call read() to get the initial content of the file.

Thus, you normally don't need to call read() at all when using watch().

To free the resources used for monitoring, call handle.remove().

file.path

A string containing the path that was passed to the cockpit.file() method.

Closing

Call the close() method on a file proxy to cancel all ongoing operations, such as reading, writing, and monitoring. The proxy should not be used after closing it.