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

Go to the source code of this file.

Typedefs

typedef struct __frbuf frbuf_t
 An opaque read file buffer type.
 

Functions

frbuf_tfrbuf_create (const char *filename)
 Creates a new read file buffer. More...
 
void frbuf_destroy (frbuf_t *buf)
 Destroys a read file buffer. More...
 
intmax_t frbuf_get_size (frbuf_t *buf)
 Returns the size (in bytes) of the a read file buffer, or -1 on error. More...
 
intmax_t frbuf_get_pos (frbuf_t *buf)
 Returns the current offset (in bytes) of a read file buffer with respect to the beginning of the file, or -1 on error. More...
 
intmax_t frbuf_set_pos (frbuf_t *buf, intmax_t pos)
 Sets the current offset (in bytes) of a read file buffer with respect to the beginning of the file. More...
 
ssize_t frbuf_read (frbuf_t *buf, void *ptr, size_t size)
 Reads bytes from the current position in a read file buffer. More...
 
ssize_t frbuf_pread (frbuf_t *buf, void *ptr, size_t size, intmax_t pos)
 Reads bytes from the specified position in a read file buffer. More...
 
const void * frbuf_map (frbuf_t *buf, intmax_t pos, size_t *psize)
 Maps (part of) the contents of a read file buffer to memory. More...
 
int frbuf_unmap (frbuf_t *buf)
 Unmaps the current memory map of a read file buffer, if it exists. More...
 

Detailed Description

This header file is part of the utilities library; it contains the read file buffer declarations.

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 reading from 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 frbuf.h.

Function Documentation

◆ frbuf_create()

frbuf_t* frbuf_create ( const char *  filename)

Creates a new read file buffer.

Parameters
filenamea pointer to the name of the file to be read into a buffer.
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
frbuf_destroy()

Definition at line 133 of file frbuf.c.

◆ frbuf_destroy()

void frbuf_destroy ( frbuf_t buf)

Destroys a read file buffer.

frbuf_unmap() is invoked, if necessary, before the file is closed.

See also
frbuf_create()

Definition at line 158 of file frbuf.c.

◆ frbuf_get_size()

intmax_t frbuf_get_size ( frbuf_t buf)

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

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

Definition at line 167 of file frbuf.c.

◆ frbuf_get_pos()

intmax_t frbuf_get_pos ( frbuf_t buf)

Returns the current offset (in bytes) of a read 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 frbuf_read() will starting reading, and it is only updated by that function or frbuf_set_pos().

Definition at line 212 of file frbuf.c.

◆ frbuf_set_pos()

intmax_t frbuf_set_pos ( frbuf_t buf,
intmax_t  pos 
)

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

The new position cannot be larger that the size of the file.

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

Definition at line 236 of file frbuf.c.

◆ frbuf_read()

ssize_t frbuf_read ( frbuf_t buf,
void *  ptr,
size_t  size 
)

Reads bytes from the current position in a read file buffer.

Note that this function updates the current position on success.

Parameters
bufa pointer to a read file buffer.
ptrthe address at which to store the bytes read.
sizethe number of bytes to read.
Returns
the number of bytes read, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
frbuf_pread()

Definition at line 270 of file frbuf.c.

◆ frbuf_pread()

ssize_t frbuf_pread ( frbuf_t buf,
void *  ptr,
size_t  size,
intmax_t  pos 
)

Reads bytes from the specified position in a read file buffer.

This function does not modify the current position.

Parameters
bufa pointer to a read file buffer.
ptrthe address at which to store the bytes read.
sizethe number of bytes to read.
posthe offset (in bytes, with respect to the beginning of the file) at which to start reading.
Returns
the number of bytes read, or -1 on error. In the latter case, the error number can be obtained with get_errc().
See also
frbuf_read()

Definition at line 301 of file frbuf.c.

◆ frbuf_map()

const void* frbuf_map ( frbuf_t buf,
intmax_t  pos,
size_t *  psize 
)

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

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

Parameters
bufa pointer to a read 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 end of the file are mapped. 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(). Note that it is an error to modify bytes in the memory map which may lead to a segmentation fault.

Definition at line 389 of file frbuf.c.

◆ frbuf_unmap()

int frbuf_unmap ( frbuf_t buf)

Unmaps the current memory map of a read file buffer, if it exists.

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

Definition at line 507 of file frbuf.c.