fd-lock 1.1.1

Advisory cross-platform lock on a file using a file descriptor to it.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

# fd-lock

[![crates.io version][1]][2] [![build status][3]][4]
[![downloads][5]][6] [![docs.rs docs][7]][8]

Advisory cross-platform file locks using file descriptors. Adapted from
[mafintosh/fd-lock].

Note that advisory lock compliance is opt-in, and can freely be ignored by other
parties. This means this crate __should never be used for security purposes__,
but solely to coordinate file access.

[mafintosh/fd-lock]: https://github.com/mafintosh/fd-lock

- [Documentation][8]
- [Crates.io][2]
- [Releases][releases]

## Examples

__Basic usage__
```rust
use fd_lock::FdLock;
use tempfile::tempfile;
use std::io::prelude::*;
use std::fs::File;

fn main() -> Result<(), failure::Error> {
    // Lock a file and write to it.
    let mut f = FdLock::new(tempfile()?);
    f.try_lock()?.write_all(b"chashu cat")?;

    // Locks can also be held for extended durations.
    let mut f = f.try_lock()?;
    f.write_all(b"nori cat")?;
    f.write_all(b"bird!")?;
    Ok(())
}
```

## Installation

```sh
$ cargo add fd-lock
```

## Safety

This crate uses `unsafe` to interface with `libc` and `winapi`. All invariants
have been carefully checked, and are manually enforced.

## Contributing

Want to join us? Check out our ["Contributing" guide][contributing] and take a
look at some of these issues:

- [Issues labeled "good first issue"][good-first-issue]
- [Issues labeled "help wanted"][help-wanted]

## References

- [LockFile function - WDC](https://docs.microsoft.com/en-us/windows/desktop/api/fileapi/nf-fileapi-lockfile)
- [flock(2) - Linux Man Page](https://linux.die.net/man/2/flock)
- [`libc::flock`](https://docs.rs/libc/0.2.58/libc/fn.flock.html)
- [`winapi::um::fileapi::LockFile`](https://docs.rs/winapi/0.3.7/x86_64-pc-windows-msvc/winapi/um/fileapi/fn.LockFile.html)

## License

[MIT](./LICENSE-MIT) OR [Apache-2.0](./LICENSE-APACHE)

[1]: https://img.shields.io/crates/v/fd-lock.svg?style=flat-square
[2]: https://crates.io/crates/fd-lock
[3]: https://img.shields.io/travis/yoshuawuyts/fd-lock/master.svg?style=flat-square
[4]: https://travis-ci.org/yoshuawuyts/fd-lock
[5]: https://img.shields.io/crates/d/fd-lock.svg?style=flat-square
[6]: https://crates.io/crates/fd-lock
[7]: https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square
[8]: https://docs.rs/fd-lock

[releases]: https://github.com/yoshuawuyts/fd-lock/releases
[contributing]: https://github.com/yoshuawuyts/fd-lock/blob/master.github/CONTRIBUTING.md
[good-first-issue]: https://github.com/yoshuawuyts/fd-lock/labels/good%20first%20issue
[help-wanted]: https://github.com/yoshuawuyts/fd-lock/labels/help%20wanted