datkt.fs

Asynchronous file system operations for Kotlin built on libuv and based on the file system API for Node.js.

Installation

The datkt.fs package an be installed with NPM.

$ npm install @datkt/fs

Prerequisites

• Kotlin/Native and the konanc command line program.

Usage

## Compile a program in 'main.kt' and link fs.klib found in `node_modules/`
$ konanc main.kt $(konanc-config -clr node_modules/@datkt/fs)

where main.kt might be

import datkt.fs.*

fun main(args: Array<String>) {
  mkdir("./directory") { err ->
    if (null != err) {
      println("Failed to make directory: ${err.message}")
    } else {
      writeFile("./directory/file", "hello world") { err ->
        if (null != err) {
          println("Failed to write file: ${err.message}")
        }
      }
    }
  }

  // kick off file system event loop
  datkt.fs.loop.run()
}

API

• object loop
• fun access(path, mode, callback)
  • Access Modes
• fun chmod(path, mode, callback)
  • File Modes
• fun chown(path, uid, gid, callback)
• fun lchown(path, uid, gid, callback)
• fun link(source, path, callback)
• fun symlink(source, path, type, callback)
• fun stat(path, callback)
• fun lstat(path, callback)
• fun mkdir(path, mode, callback)
• fun readdir(path, callback)
• fun open(path, flags, mode, callback)
  • File System Flags
• class Stats(...)
  • Stats.hasMode(mode)
  • Stats.isCharacterDevice()
  • Stats.isSymbolicLink()
  • Stats.isBlockDevice()
  • Stats.isDirectory()
  • Stats.isSocket()
  • Stats.isFIFO()
  • Stats.isFile()

object loop { ... }

An object that represents an interface into the uv event loop used internally for asynchronous work done by the functions exposed in this package. datkt.fs.loop.run() will invoke any queued work for the event loop.

object loop {
  fun run(): Int
  fun stop()
}

loop.run()

Invoke the uv event loop. Calls uv_run internally.

loop.stop()

Stop the uv event loop. Calls uv_stop internally.

access(path: String, mode: Long = F_OK, callback: (Error?) -> Unit?)

Test user permissions for a file specified at path and mode calling callback with an Error if one errors.

access("/home") { err ->
  if (null != err) {
    println("Something went wrong checking access to /home")
  }
}

Access Modes

The possible values for the mode argument to test file access permissions can be seen below.

• F_OK - Test for the existence of a file
• R_OK - Test for read permissions on a file
• W_OK - Test for write permissions on a file
• X_OK - Test for execution permissions on a file

chmod(path: String, mode: Long, callback: Callback)

Change user permissions of a file specified at path and mode calling callback with an Error if one occurs.

// make read, write, execute permissions for everyone
val mode = (
  S_IRUSR or S_IWUSR or S_IXUSR or
  S_IRGRP or S_IWGRP or S_IXGRP or
  S_IROTH or S_IWOTH or S_IXOTH
)

// modify program permissions
chmod("/home/program", mode) { err ->
  if (null != err) {
    println("Something went wrong changing program permissions: ${err.message}")
  }
}

File Modes

The possible values for the mode argument can be seen below. They can be grouped into a bit mask by the logical OR (or) operator.

• S_IRWXU - Read, write, and execute by owner (700)
• S_IRUSR - Read by owner (400)
• S_IWUSR - Write by owner (200)
• S_IXUSR - Execute by owner (100)
• S_IRWXG - Read, write, and Execute by group (070)
• S_IRGRP - Read by group (040)
• S_IWGRP - Write by group (020)
• S_IXGRP - Execute by group (010)
• S_IRWXO - Read, write, and execute by others (007)
• S_IROTH - Read by others (004)
• S_IWOTH - Write by others (002)
• S_IXOTH - Execute by others (001)

chown(path: String, uid: Long, gid: Long, callback: Callback)

Change user and group ownership of a file specified at path for user id uid, and group id gid calling callback with an Error, if one occurs.

chown("/home/file", 1000, 10) { err ->
  if (null != err) {
    println("Something went wrong changing file ownership: ${err.message}")
  }
}

lchown(path: String, uid: Long, gid: Long, callback: Callback)

Change user and group ownership of a symbolic link specified at path for user id uid, and group id gid calling callback with an Error, if one occurs.

symlink("/home/file", "/home/link") { err ->
  lchown("/home/link", 1000, 10) { err ->
    if (null != err) {
      println("Something went wrong changing link ownership: ${err.message}")
    }
  }
}

link(source: String, path: String, callback: Callback)

Create a new hard link at path for a file specified at source calling callback with an Error, if one occurs.

link("/home/file", "/home/link") { err ->
  if (null != err) {
    println("Something went creating hard link: ${err.message}")
  }
}

symlink(source: String, path: String, type: Int = 0, callback: Callback)

symlink("/home/file", "/home/symlink") { err ->
  if (null != err) {
    println("Something went creating soft link: ${err.message}")
  }
}

stat(path: String, callback: Callback)

Query the stats of a file specified at path, if it exists, calling callback with an Error, if one occurs, otherwise an instance of Stats as the second argument.

stat("/home/file") { err, stats ->
  if (null != err) {
    println(err.message)
  } else {
    println(stats)
  }
}

lstat(path: String, callback: Callback)

Query the stats of a file specified at path, if it is a link or file, calling callback with an Error, if one occurs, otherwise an instance of Stats as the second argument.

lstat("/home/file") { err, stats ->
  if (null != err) {
    println(err.message)
  } else {
    println(stats)
  }
}

mkdir(path: String, mode: Long = DEFAULT_MKDIR_MODE, callback: Callback)

Make a directory specified at path with with mode calling calling with an Error, if one occurs. The mode defaults to DEFAULT_MKDIR_MODE (see below) if not specified.

mkdir("/path/to/directory") { err ->
  if (null != err) {
    println(err.message)
  }
}

Modes

See File Modes for a list of all file modes. The default mode is defined by the DEFAULT_MKDIR_MODE constant.

val DEFAULT_MKDIR_MODE = (S_IRWXU or S_IRWXG or S_IRWXO)

readdir(path: String, callback: Callback)

Read a directory specified at path for files entries calling callback with an Error, if one occurs, otherwise an Array<String> with file names.

readdir("/home") { err, entries, ->
  for (entry in entries) {
    println(entry)
  }
}

`open(path: String, flags: String = "r", mode: Long = DEFAULT_OPEN_MODE, callback: Callback)

Open a file specified at path with optional flags and mode calling callback with an Error, if one occurs, otherwise with a valid file descriptor.

open("/path/to/file") { err, fd ->
  if (null != err) {
    println(err.message)
  } else {
    // do something with fd
  }
}

By default, all files will be opened in DEFAULT_OPEN_MODE where:

// equivalent to (0666)
val DEFAULT_OPEN_MODE = (
  S_IRUSR or S_IWUSR or
  S_IRGRP or S_IWGRP or
  S_IROTH or S_IWOTH
)

File System Flags

• "r" - Open file for reading. An error occurs if the file does not exist.
• "r+" - Open file for reading and writing. An error occurs if the file does not exist.
• "w" - Open file for writing. The file is created if it does not exist, otherwise it is truncated.
• "w+" - Open file for reading and writing. The file is created if it does not exist, otherwise it is truncated.
• "a" - Open file for appending. Writes start at the end of the file. The file is created if it does not exist, otherwise it is truncated.

class Stats(...)

Represents a data class containing stat properties of a file.

class Stats(
  val dev: Long = 0,
  val mode: Long = 0,
  val nlink: Long = 0,
  val uid: Long = 0,
  val gid: Long = 0,
  val rdev: Long = 0,
  val ino: Long = 0,
  val size: Long = 0,
  val blksize: Long = 0,
  val blocks: Long = 0,
  val atime: Long = 0,
  val mtime: Long = 0,
  val ctime: Long = 0,
  val birthtime: Long = 0
)

Stats.hasMode(mode: Long): Boolean

Check if a given mode is present in the stat's mode bit field.

if (stat.hasMode(S_IFREG)) {
  // stat points to a regular file
}

Stats.isCharacterDevice(): Boolean

Check if the stat points to a character device. Equivalent to stat.hasMode(S_IFCHR).

if (stat.isCharacterDevice()) {
  // stat points to a character device
}

Stats.isSymbolicLink(): Boolean

Check if the stat points to a symbolic link. Equivalent to stat.hasMode(S_IFLNK).

if (stat.isSymbolicLink()) {
  // stat points to a symbolic link
}

Stats.isBlockDevice(): Boolean

Check if the stat points to a block device. Equivalent to stat.hasMode(S_IFBLK).

if (stat.isBlockDevice()) {
  // stat points to a block device
}

Stats.isDirectory(): Boolean

Check if the stat points to a directory. Equivalent to stat.hasMode(S_IFDIR).

if (stat.isDirectory()) {
  // stat points to a directory
}

Stats.isSocket(): Boolean

Check if the stat points to a socket. Equivalent to stat.hasMode(S_IFSOCK).

if (stat.isSocket()) {
  // stat points to a socket
}

Stats.isFIFO(): Boolean

Check if the stat points to a FIFO. Equivalent to stat.hasMode(S_IFIFO).

if (stat.isFIFO()) {
  // stat points to a FIFO (named pipe)
}

Stats.isFile(): Boolean

Check if the stat points to a regular file. Equivalent to stat.hasMode(S_IFREG).

if (stat.isFile()) {
  // stat points to a file
}

License

MIT