Skip to content

Commit

Permalink
docs: mention breaking changes in next release note
Browse files Browse the repository at this point in the history
  • Loading branch information
i10416 committed Jan 4, 2023
1 parent 174e9df commit 4e2096f
Showing 1 changed file with 69 additions and 0 deletions.
69 changes: 69 additions & 0 deletions docs/changelog/0.5.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,75 @@ Javadoc and JVM output:
throw new IllegalArgumentException("URI is not absolute")
}
```

### Replace time_t fields with timespec in POSIX sys/stat.scala

In order to support nanosecond resolution for `java.nio.file.attribute.BasicFileAttributes`, we introduce breaking changes to sys/stat struct.

Previously, `stat` struct was defined as following and you were able to access second resolution file stat fields `st_atime`, `st_mtime` and `st_ctime` by `_7`, `_8` and `_9`.

```scala
type stat = CStruct13[
dev_t, // st_dev
dev_t, // st_rdev
ino_t, // st_ino
uid_t, // st_uid
gid_t, // st_gid
off_t, // st_size
time_t, // st_atime
time_t, // st_mtime
time_t, // st_ctime
blkcnt_t, // st_blocks
blksize_t, // st_blksize
nlink_t, // st_nlink
mode_t // st_mode
]
```

Since 0.5.0, `stat` struct uses `timespec` for file stat fields. Therefore, you need to replace `_7`, `_8` and `_9` with `_7._1`, `_8._1` and `_9._1` to access those fields.

```scala
type stat = CStruct13[
dev_t, // st_dev
dev_t, // st_rdev
ino_t, // st_ino
uid_t, // st_uid
gid_t, // st_gid
off_t, // st_size
timespec, // st_atim or st_atimespec
timespec, // st_mtim or st_mtimespec
timespec, // st_ctim or st_ctimespec
blkcnt_t, // st_blocks
blksize_t, // st_blksize
nlink_t, // st_nlink
mode_t // st_mode
]
```

There is a helper implicit class `statOps`, which provides human-friendly field accessors like `st_dev` or `st_rdev`. It is recommended to use these fields from `statOps` rather than accessing fields by `_N`.

For example, import `scala.scalanative.posix.timeOps._` and `scala.scalanative.posix.sys.statOps.statOps`, then you can get the last access time of a file by `st_atime` or `st_atim` field.

```scala
import scala.scalanative.unsafe._
import scala.scalanative.posix.sys.stat
import scala.scalanative.posix.timeOps._
import scala.scalanative.posix.sys.statOps.statOps

Zone { implicit z =>
val filepath = c"/path/to/file"
val stat = alloc[stat.stat]()
stat.stat(filepath, stat)
// directly get the last access time in second resolution
val atime = stat.st_atime
// get the last access time in second resolution from timespec
val atimesec = stat.st_atim.tv_sec
// get access time in nanosecond resolution from timespec
val atimensec = stat.st_atim.tv_nsec
}

```

## Deprecated definitions

### Removed in this version
Expand Down

0 comments on commit 4e2096f

Please sign in to comment.