Lely core libraries  2.3.4
fwbuf.h File Reference
#include <lely/libc/sys/types.h>
#include <lely/util/util.h>
#include <stddef.h>
#include <stdint.h>
Include dependency graph for fwbuf.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct __fwbuf fwbuf_t
 An opaque (atomic) write file buffer type.
 

Functions

fwbuf_tfwbuf_create (const char *filename)
 Creates a new (atomic) write file buffer. More...
 
void fwbuf_destroy (fwbuf_t *buf)
 Destroys a write file buffer. More...
 
intmax_t fwbuf_get_size (fwbuf_t *buf)
 Returns the current size (in bytes) of the a write file buffer, or -1 on error. More...
 
int fwbuf_set_size (fwbuf_t *buf, intmax_t size)
 Sets the new size (in bytes) of the a write file buffer. More...
 
intmax_t fwbuf_get_pos (fwbuf_t *buf)
 Returns the current offset (in bytes) of a write file buffer with respect to the beginning of the file, or -1 on error. More...
 
intmax_t fwbuf_set_pos (fwbuf_t *buf, intmax_t pos)
 Sets the current offset (in bytes) of a write file buffer with respect to the beginning of the file. More...
 
ssize_t fwbuf_write (fwbuf_t *buf, const void *ptr, size_t size)
 Writes bytes to the current position in a write file buffer. More...
 
ssize_t fwbuf_pwrite (fwbuf_t *buf, const void *ptr, size_t size, intmax_t pos)
 Writes bytes to the specified position in a write file buffer. More...
 
void * fwbuf_map (fwbuf_t *buf, intmax_t pos, size_t *psize)
 Maps (part of) the contents of a write file buffer to memory. More...
 
int fwbuf_unmap (fwbuf_t *buf)
 Unmaps the current memory map of a write file buffer, if it exists, and writes the changes to disk. More...
 
void fwbuf_clearerr (fwbuf_t *buf)
 Clears the error indicator of a write file buffer, allowing fwbuf_commit() to write the file to disk. More...
 
int fwbuf_error (fwbuf_t *buf)
 Returns 1 if the error indicator of a write file buffer is set, and 0 if not. More...
 
void fwbuf_cancel (fwbuf_t *buf)
 Cancels any further file operations by setting the error indicator of a write file buffer to ERRNUM_CANCELED (if it was not already set).
 
int fwbuf_commit (fwbuf_t *buf)
 Commits all changes to a write file buffer to disk if all previous file operations were successful, or discards them if not. More...
 

Detailed Description

This header file is part of the utilities library; it contains the (atomic) write file buffer declarations.

The write file buffer is atomic because all file operations are performed on a temporary file. Only once all file operations have successfully completed and fwbuf_commit() is invoked without error is the final file created (or replaced). If any error occurs, the temporary file is discarded. This guarantees that either the previous version or the complete new version of the file is present on disk, even in the case of abnormal termination. Note that this can only be guaranteed on Windows and POSIX platforms. On other platforms we can only make a best effort.

The file buffer allows mapping (part of) the contents of the file to memory. This makes it possible to use pointer manipulation and functions like memcpy() instead of writing to the file explicitly. The implementation uses CreateFileMapping()/MapViewOfFile() or mmap() if available.

Author
J. S. Seldenthuis jseld.nosp@m.enth.nosp@m.uis@l.nosp@m.ely..nosp@m.com

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Definition in file fwbuf.h.

Function Documentation

◆ fwbuf_create()

fwbuf_t* fwbuf_create ( const char *  filename)

Creates a new (atomic) write file buffer.

Parameters
filenamea pointer to the name of the file to be created or replaced once all file operations have completed successfully.
Returns
a pointer to a new file buffer, or NULL on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_destroy()

Definition at line 305 of file fwbuf.c.

◆ fwbuf_destroy()

void fwbuf_destroy ( fwbuf_t buf)

Destroys a write file buffer.

fwbuf_unmap() is invoked, if necessary, before the file is closed. If fwbuf_commit() was invoked and did not return an error, the file is created (or replaced), otherwise it is discarded.

See also
fwbuf_create()

Definition at line 330 of file fwbuf.c.

◆ fwbuf_get_size()

intmax_t fwbuf_get_size ( fwbuf_t buf)

Returns the current size (in bytes) of the a write file buffer, or -1 on error.

In the latter case, the error number can be obtained with get_errc().

See also
fwbuf_set_size()

Definition at line 339 of file fwbuf.c.

◆ fwbuf_set_size()

int fwbuf_set_size ( fwbuf_t buf,
intmax_t  size 
)

Sets the new size (in bytes) of the a write file buffer.

This function invokes fwbuf_unmap() before changing the size. Depending on the platform, it may not be possible to discard bytes already written to the file, putting a lower limit on the file size.

Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_get_size()

Definition at line 369 of file fwbuf.c.

◆ fwbuf_get_pos()

intmax_t fwbuf_get_pos ( fwbuf_t buf)

Returns the current offset (in bytes) of a write file buffer with respect to the beginning of the file, or -1 on error.

In the latter case, the error number can be obtained with get_errc().

The position indicates the location at which the next call to fwbuf_write() will start writing, and it is only updated by that function or fwbuf_set_pos().

Definition at line 415 of file fwbuf.c.

◆ fwbuf_set_pos()

intmax_t fwbuf_set_pos ( fwbuf_t buf,
intmax_t  pos 
)

Sets the current offset (in bytes) of a write file buffer with respect to the beginning of the file.

The new position may be larger than the current size of the file. In that case the file is extended with zeros the moment data is written to the new position.

Returns
the new position, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_get_pos()

Definition at line 447 of file fwbuf.c.

◆ fwbuf_write()

ssize_t fwbuf_write ( fwbuf_t buf,
const void *  ptr,
size_t  size 
)

Writes bytes to the current position in a write file buffer.

Note that this function updates the current position (and the memory map, if it exists) on success.

Parameters
bufa pointer to a write file buffer.
ptrta pointer to the bytes to write.
sizethe number of bytes to write.
Returns
the number of bytes written, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_pwrite()

Definition at line 489 of file fwbuf.c.

◆ fwbuf_pwrite()

ssize_t fwbuf_pwrite ( fwbuf_t buf,
const void *  ptr,
size_t  size,
intmax_t  pos 
)

Writes bytes to the specified position in a write file buffer.

This function does not modify the current position. It does update the memory map, if it exists (see fwbuf_map()).

Parameters
bufa pointer to a write file buffer.
ptrta pointer to the bytes to write.
sizethe number of bytes to write.
posthe offset (in bytes, with respect to the beginning of the file) at which to start writing.
Returns
the number of bytes written, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_write()

Definition at line 543 of file fwbuf.c.

◆ fwbuf_map()

void* fwbuf_map ( fwbuf_t buf,
intmax_t  pos,
size_t *  psize 
)

Maps (part of) the contents of a write file buffer to memory.

Only a single memory map can exists at a time. This function invokes fwbuf_unmap() before creating the map.

Parameters
bufa pointer to a write file buffer.
posthe offset (in bytes, with respect to the beginning of the file) at which to the memory map.
psizethe address of a value containing the desired size (in bytes) of the memory map. If psize or *psize is zero, all bytes from pos until the (current) end of the file are mapped. It is not possible to extend the map beyond the current end of the file. On success, *psize contains the size of the map.
Returns
a pointer to the first byte in the memory map, or NULL on error. In the latter case, the error number can be obtained with get_errc().

Definition at line 658 of file fwbuf.c.

◆ fwbuf_unmap()

int fwbuf_unmap ( fwbuf_t buf)

Unmaps the current memory map of a write file buffer, if it exists, and writes the changes to disk.

Returns
0 on success, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
fwbuf_map()

Definition at line 827 of file fwbuf.c.

◆ fwbuf_clearerr()

void fwbuf_clearerr ( fwbuf_t buf)

Clears the error indicator of a write file buffer, allowing fwbuf_commit() to write the file to disk.

See also
fwbuf_error()

Definition at line 928 of file fwbuf.c.

◆ fwbuf_error()

int fwbuf_error ( fwbuf_t buf)

Returns 1 if the error indicator of a write file buffer is set, and 0 if not.

In the former case, the error number of the first error encountered during a file operation can be obtained with get_errc().

See also
fwbuf_clearerr()

Definition at line 942 of file fwbuf.c.

◆ fwbuf_commit()

int fwbuf_commit ( fwbuf_t buf)

Commits all changes to a write file buffer to disk if all previous file operations were successful, or discards them if not.

This function does not return until all changes are physically written to disk. Any further file operations will fail.

Returns
0 on success, or -1 on error. In the latter case, the error number of the first error encountered during a file operation can be obtained with get_errc().

Definition at line 979 of file fwbuf.c.