stackbuilders / atomic-write

Writes files atomically in Haskell while preserving permissions

Atomic Write

Atomic Write assists with atomic modification of files using Haskell. It is a wrapper for using the atomic mv(1) operation which correctly sets permissions based on the original file, or on system defaults if no file previously exists.

How it works

On most Unix systems, mv is an atomic operation. This makes it simple to write to a file atomically just by using the mv operation. However, this will destroy the permissions on the original file. This library does the following to preserve permissions while atomically writing to a file:

If an original file exists, take those permissions and apply them to the temp file before mving the file into place.

If the original file does not exist, create a following with default permissions (based on the currently-active umask).

This way, when the file is mv'ed into place, the permissions will be the ones held by the original file.

This library is based on similar implementations found in common libraries in Ruby and Python:

• Ruby on Rails includes a similar method called atomic_write

• Chef includes atomic update functionality

• There is a python library for atomically updating a file

Usage

To use atomic-write, import the module corresponding to the type you wish to write atomically, e.g., to write a (strict) ByteString atomically:

import System.AtomicWrite.Writer.ByteString

Then you can use the atomicWriteFile function that accepts a FilePath and a ByteString, e.g.:

atomicWriteFile myFilePath myByteString

See the Haddock documentation.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Justin S. Leitgeb 💻	William R. Arellano 💻	Alexander Mejía 💻	Agustin Camino 💻	Juan Paucar 💻	Barbara Morantes 💡
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT, see the LICENSE file.

Contributing

Do you want to contribute to this project? Please take a look at our contributing guideline to know how you can help us build it.

---

Check out our libraries | Join our team

atomic-write's Issues

Allow setting permissions

It would be handy to be able to set permissions for new files.

Add version boundaries to dependencies

Currently most of the dependencies of the library do not have proper version boundaries, we should add them.

hackage docs example is wrong

example says atomicWrite myFilePath myByteString, correct would be atomicWriteFile myFilePath myByteString

Suggestion: atomicReplaceFile as an alias for atomicWriteFile

On most unix-y systems, the technique used to modify a file by creating and replacing will not appear to be modifying the file from the perspective of programs that already have the file open. This matters common operations like log rotation. Adding atomicReplaceFile = atomicWriteFile would not be an API change, and would allow users of the library to be a bit more clear in their code when the occasion calls for it.

Could not find module ‘System.PosixCompat.Files’

I get this when I add atomic-write to my project's .cabal file and try to cabal v2-build:

Resolving dependencies...
Build profile: -w ghc-8.8.2 -O1
In order, the following will be built (use -v for more details):
 - atomic-write-0.2.0.7 (lib) (requires build)
 - kalyn-0 (exe:kalyn) (configuration changed)
Starting     atomic-write-0.2.0.7 (lib)
Building     atomic-write-0.2.0.7 (lib)

Failed to build atomic-write-0.2.0.7.
Build log (
/home/raxod502/.cabal/logs/ghc-8.8.2/atomic-write-0.2.0.7-b62483df2180d2241be3f29b116f1d8e6315280baf54b91c552b0d9b7a5d8506.log
):
Configuring library for atomic-write-0.2.0.7..
Preprocessing library for atomic-write-0.2.0.7..
Building library for atomic-write-0.2.0.7..
[ 1 of 12] Compiling System.AtomicWrite.Internal ( src/System/AtomicWrite/Internal.hs, dist/build/System/AtomicWrite/Internal.o )

src/System/AtomicWrite/Internal.hs:21:1: error:
    Could not find module ‘System.PosixCompat.Files’
    There are files missing in the ‘unix-compat-0.5.2’ package,
    try running 'ghc-pkg check'.
    Use -v (or `:set -v` in ghci) to see a list of the files searched for.
   |
21 | import           System.PosixCompat.Files (fileMode, getFileStatus, setFileMode)
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
cabal: Failed to build atomic-write-0.2.0.7 (which is required by exe:kalyn
from kalyn-0). See the build log above for details.

Running ghc-pkg returns exclusively lines noting missing files under /usr/share/doc, so that does not appear to be the issue.

add a call to fsync()?

I think this package would be more useful if there was a call to fsync() as well, at least optionally, as with http://hackage.haskell.org/package/safeio-0.0.5.0/docs/src/System-IO-SafeWrite.html#withOutputFile ?

Update ghc versions on TravisCI

The current versions of GHC in TravisCI are too old.

Add other modules to test suite

There's no other modules section in the test suite component, so the Hackage package has no tests:

Warning: modules not listed in atomic-write.cabal for 'atomic-write-test' component (add to other-modules):
    System.AtomicWrite.Internal
    System.AtomicWrite.Writer.ByteString
    System.AtomicWrite.Writer.ByteStringBuilder
    System.AtomicWrite.Writer.ByteStringBuilderSpec
    System.AtomicWrite.Writer.ByteStringSpec
    System.AtomicWrite.Writer.LazyByteString
    System.AtomicWrite.Writer.LazyByteStringSpec
    System.AtomicWrite.Writer.String
    System.AtomicWrite.Writer.StringSpec
    System.AtomicWrite.Writer.Text
    System.AtomicWrite.Writer.TextSpec

Also, the atomic-write library should be listed as a build dependency of the test suite.

atomic-write writes over read only files

This is a little odd, although understandable given the implementation.

Invalid ghc-options on upload to Hackage

Trying to upload the package to hackage gives me

'ghc-options: -Wall -Werror' makes the package very easy to break with future GHC versions because new GHC versions often add new warnings. Use just 'ghc-options: -Wall' instead. Alternatively, if you want to use this, make it conditional based on a Cabal configuration flag (with 'manual: True' and 'default: False') and enable that flag during development.

Add basic usage examples

The library is simple, but having a small example of the different ways that this can be helpful to get started with the library and find the use cases and limitations for this package.

allow base 4.9

could be done as simply as editing the cabal metadata, or cutting a new release, whichever you prefer

Add missing documentation

Haddock coverage is low because of missing documentation for module headers.

Newline adjustments on Windows?

The documentation for System.IO.openBinaryFile says:

On Windows, reading a file in text mode (which is the default) will translate CRLF to LF, and writing will translate LF to CRLF. This is usually what you want with text files. With binary files this is undesirable; also, as usual under Microsoft operating systems, text mode treats control-Z as EOF. Binary mode turns off all special treatment of end-of-line and end-of-file characters. (See also hSetBinaryMode.)

My current understanding is that this library opens all files in text mode and will therefore apply these newline adjustments on Windows, even for e.g. ByteString.

Is this correct? Could you offer binary mode variants in this case or maybe just default to binary mode for (lazy) ByteStrings?

Add a CHANGELOG

We don't have a changelog, Why?

Add All Contributors

Migrate to GitHub Actions