--- created_at: '2016-05-30T21:52:01.000Z' title: Things Unix can do atomically (2010) url: https://rcrowley.org/2010/01/06/things-unix-can-do-atomically.html author: turrini points: 207 story_text: comment_text: num_comments: 62 story_id: story_title: story_url: parent_id: created_at_i: 1464645121 _tags: - story - author_turrini - story_11803431 objectID: '11803431' --- This is a catalog of things UNIX-like/POSIX-compliant operating systems can do atomically, making them useful as building blocks for thread-safe and multi-process-safe programs without mutexes or read/write locks.  The list is by no means exhaustive and I expect it to be updated frequently for the foreseeable future. The philosophy here is to let the kernel do as much work as possible.  At my most pessimistic, I trust the kernel developers more than a trust myself.  More practically, it’s stupid to spend CPU time locking around an operation that’s already atomic.  Added 2010-01-07. ## Operating on a pathname The operations below are best left to local filesystems.  More than a few people have written in crying foul if any of these techniques are used on an NFS mount.  True.  When there are multiple kernels involved, the kernel can’t very well take care of all the locking for us.  Added 2010-01-06. - `mv -T ` atomically changes the target of `` to the directory pointed to by `` and is indispensable when deploying new code.  Updated 2010-01-06: both operands are symlinks.  (So this isn’t a system call, it’s still useful.)  A reader pointed out that `ln -Tfs ` accomplishes the same thing without the second symlink.  Added 2010-01-06.  Deleted 2010-01-06: `strace(1)` shows that `ln -Tfs ` actually calls `symlink(2)`, `unlink(2)`, and `symlink(2)` once more, disqualifying it from this page.  `mv -T ` ends up calling `rename(2)` which can atomically replace ``.  Caveat 2013-01-07: this does not apply to Mac OS X, whose [`mv(1)`](https://developer.apple.com/library/mac/#documentation/Darwin/Reference/Manpages/man1/mv.1.html) doesn’t call `rename(2)`.  [`mv(1)`](http://linux.die.net/man/1/mv). - `link(oldpath, newpath)` creates a new hard link called `newpath` pointing to the same inode as `oldpath` and increases the link count by one.  This will fail with the error code `EEXIST` if `newpath` already exists, making this a useful mechanism for locking a file amongst threads or processes that can all agree upon the name `newpath`.  I prefer this technique for whole-file locking because the lock is visible to `ls(1)`.  [`link(2)`](http://linux.die.net/man/2/link). - `symlink(oldpath, newpath)` operates very much like `link(2)` but creates a symbolic link at a new inode rather than a hard link to the same inode.  Symbolic links can point to directories, which hard links cannot, making them a perfect analogy to `link(2)` when locking entire directories.  This will fail with the error code `EEXIST` if `newpath` already exists, making this a perfect analogy to `link(2)` that works for directories, too.  Be careful of symbolic links whose target inode has been removed ("dangling" symbolic links) — `open(2)` will fail with the error code `ENOENT`.  It should be mentioned that inodes are a finite resource (this particular machine has 1,245,184 inodes).  [`symlink(2)`](http://linux.die.net/man/2/symlink).  Added 2010-01-07 - `rename(oldpath, newpath)` can change a pathname atomically, provided `oldpath` and `newpath` are on the same filesystem.  This will fail with the error code `ENOENT` if `oldpath` does not exist, enabling interprocess locking much like `link(oldpath, newpath)` above.  I find this technique more natural when the files in question will be `unlink`ed later.  [`rename(2)`](http://linux.die.net/man/2/rename). - `open(pathname, O_CREAT | O_EXCL, 0644)` creates and opens a new file.  (Don’t forget to set the mode in the third argument\!)  `O_EXCL` instructs this to fail with the error code `EEXIST` if `pathname` exists.  This is a useful way to decide which process should handle a task: whoever successfully creates the file.  [`open(2)`](http://linux.die.net/man/2/open). - `mkdir(dirname, 0755)` creates a new directory but fails with the error code `EEXIST` if `dirname` exists.  This provides for directories the same mechanism `link(2)` `open(2)` with `O_EXCL` provides for files.  [`mkdir(2)`](http://linux.die.net/man/2/mkdir).  Added 2010-01-06; edited 2013-01-07. ## Operating on a file descriptor - `fcntl(fd, F_GETLK, &lock)`, `fcntl(fd, F_SETLK, &lock)`, and `fcntl(fd, F_SETLKW, &lock)` allow cooperating processes to lock regions of a file to serialize their access.  `lock` is of type `struct flock` and describes the type of lock and the region being locked.  `F_SETLKW` is particularly useful as it blocks the calling process until the lock is acquired.  There is a “mandatory locking” mode but Linux’s implementation is unreliable as it’s subject to a race condition.  [`fcntl(2)`](http://linux.die.net/man/2/fcntl). - `fcntl(fd, F_GETLEASE)` and `fcntl(fd, F_SETLEASE, lease)` ask the kernel to notify the calling process with `SIGIO` when another process `open`s or `truncate`s the file referred to by `fd`.  When that signals arrives, the lease needs to be removed by `fcntl(fd, F_SETLEASE, F_UNLCK)`.  `fcntl(fd, F_NOTIFY, arg)` is similar but doesn’t block other processes, so it isn’t useful for synchronization.  [`fcntl(2)`](http://linux.die.net/man/2/fcntl). - `mmap(0, length, PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0)` returns a pointer from which a file’s contents can be read and written by normal memory operations.  By making frequent use of `msync(addr, length, MS_INVALIDATE)`, data written in this manner can be shared between processes that both map the same file.  [`mmap(2)`](http://linux.die.net/man/2/mmap), [`msync(2)`](http://linux.die.net/man/2/msync). ## Operating on virtual memory - `__sync_fetch_and_add`, `__sync_add_and_fetch`, `__sync_val_compare_and_swap`, and friends provide a full barrier so “no memory operand will be moved across the operation, either forward or backward.” These operations are the basis for most (all?) lock-free algorithms.  [GCC Atomic Builtins](http://gcc.gnu.org/onlinedocs/gcc-4.1.2/gcc/Atomic-Builtins.html). Something I should add to my repertoire?  Race condition?  Let me know at or [@rcrowley](http://twitter.com/rcrowley) and I’ll fix it.