Lely core libraries 2.3.4
frbuf.c File Reference

This file is part of the utilities library; it contains the implementation of the read file buffer. More...

#include "util.h"
#include <lely/util/errnum.h>
#include <lely/util/frbuf.h>
#include <assert.h>
#include <stdlib.h>
#include <stdio.h>
#include <fcntl.h>
#include <sys/mman.h>
#include <sys/stat.h>
Include dependency graph for frbuf.c:

Go to the source code of this file.

Data Structures

struct  __frbuf
 An read file buffer struct. More...
 

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 file is part of the utilities library; it contains the implementation of the read file buffer.

See also
lely/util/frbuf.h
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.c.

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 138 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 163 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 172 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 217 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 241 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 275 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 306 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 394 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 513 of file frbuf.c.