Lely core libraries
2.3.4
|
This header file is part of the utilities library; it contains the (atomic) write file buffer declarations. More...
#include <lely/libc/sys/types.h>
#include <lely/util/util.h>
#include <stddef.h>
#include <stdint.h>
Go to the source code of this file.
Typedefs | |
typedef struct __fwbuf | fwbuf_t |
An opaque (atomic) write file buffer type. | |
Functions | |
fwbuf_t * | fwbuf_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... | |
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.
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.
fwbuf_t* fwbuf_create | ( | const char * | filename | ) |
Creates a new (atomic) write file buffer.
filename | a pointer to the name of the file to be created or replaced once all file operations have completed successfully. |
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.
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().
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.
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().
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.
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.
buf | a pointer to a write file buffer. |
ptr | ta pointer to the bytes to write. |
size | the number of bytes to write. |
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()).
buf | a pointer to a write file buffer. |
ptr | ta pointer to the bytes to write. |
size | the number of bytes to write. |
pos | the offset (in bytes, with respect to the beginning of the file) at which to start writing. |
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.
buf | a pointer to a write file buffer. |
pos | the offset (in bytes, with respect to the beginning of the file) at which to the memory map. |
psize | the 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. |
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.
void fwbuf_clearerr | ( | fwbuf_t * | buf | ) |
Clears the error indicator of a write file buffer, allowing fwbuf_commit() to write the file to disk.
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().
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.