rtl-obj-cache.h File Reference

RTEMS Run-Time Linker Object File cache buffers a section of the object file in a buffer to localise read performance. More...

#include <fcntl.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

Go to the source code of this file.

Data Structures
struct	rtems_rtl_obj_cache

Typedefs
typedef struct rtems_rtl_obj_cache	rtems_rtl_obj_cache

Functions
bool	rtems_rtl_obj_cache_open (rtems_rtl_obj_cache *cache, size_t size)
void	rtems_rtl_obj_cache_close (rtems_rtl_obj_cache *cache)
void	rtems_rtl_obj_cache_flush (rtems_rtl_obj_cache *cache)
bool	rtems_rtl_obj_cache_read (rtems_rtl_obj_cache *cache, int fd, off_t offset, void **buffer, size_t *length)
bool	rtems_rtl_obj_cache_read_byval (rtems_rtl_obj_cache *cache, int fd, off_t offset, void *buffer, size_t length)

Detailed Description

RTEMS Run-Time Linker Object File cache buffers a section of the object file in a buffer to localise read performance.

This is a simple object file cache that holds a buffer of data from the offset in the file the read is requested from. Writes are not supported.

The cache holds the file descriptor, the offset into the file and the amount of valid data in the cache. If the file is ever modified the user of the cache to responsible for flushing the cache. For example the cache should be flused if the file is closed.

The cache can return by reference or by value. By reference allow access to the cache buffer. Do not modify the cache's data. By value will copy the requested data into the user supplied buffer.

The read by reference call allows you to probe the file's data. For example a string in an object file can be an unknown length. You can request a read up to the cache's size by reference. The code will attempt to have this data in the buffer. If there is not enough data in the file the length will be modifed to reflect this.

You can have more than one cache for a single file all looking at different parts of the file.

Typedef Documentation

rtems_rtl_obj_cache

typedef struct rtems_rtl_obj_cache rtems_rtl_obj_cache

The buffer cache.

Function Documentation

rtems_rtl_obj_cache_close()

void rtems_rtl_obj_cache_close

(

rtems_rtl_obj_cache *

cache

)

Close a cache.

Parameters

cache

The cache to close.

rtems_rtl_obj_cache_flush()

void rtems_rtl_obj_cache_flush

(

rtems_rtl_obj_cache *

cache

)

Flush the cache. Any further read will read the data from the file.

Parameters

cache

The cache to flush.

rtems_rtl_obj_cache_open()

bool rtems_rtl_obj_cache_open	(	rtems_rtl_obj_cache *	cache,
		size_t	size
	)

Open a cache allocating a single buffer of the size passed. The default state of the cache is flushed. No already open checks are made.

Parameters

cache	The cache to initialise.
size	The size of the cache.

Return values

true	The cache is open.
false	The cache is not open. The RTL error is set.

rtems_rtl_obj_cache_read()

bool rtems_rtl_obj_cache_read	(	rtems_rtl_obj_cache *	cache,
		int	fd,
		off_t	offset,
		void **	buffer,
		size_t *	length
	)

Read data by reference. The length contains the amount of data that should be available in the cache and referenced by the buffer handle. It must be less than or equal to the size of the cache. This call will return the amount of data that is available. It can be less than you ask if the offset and size is past the end of the file.

Parameters

cache	The cache to reference data from.
fd	The file descriptor. Must be an open file.
offset	The offset in the file to reference the data to.
buffer	The location to reference the data from.
length	The length of data to reference. Can be modified to a lesser value and true is still returned so check it.

Return values

true	The data referenced is in the cache.
false	The read failed and the RTL error has been set.

rtems_rtl_obj_cache_read_byval()

bool rtems_rtl_obj_cache_read_byval	(	rtems_rtl_obj_cache *	cache,
		int	fd,
		off_t	offset,
		void *	buffer,
		size_t	length
	)

Read data by value. The data is copied to the user supplied buffer.

Parameters

cache	The cache to read the data from.
fd	The file descriptor. Must be an open file.
offset	The offset in the file to read the data from.
buffer	The location the data is written into.
length	The length of data to read.

Return values

true	The data has been read from the cache.
false	The read failed and the RTL error has been set.