ntar.h File Reference

Detailed Description

This file contains prototypes, definitions and data structures of the ntar library.

#include <stdio.h>
#include "block_headers.h"
#include "plugins.h"

Go to the source code of this file.

Defines

#define NTAR_SUCCESS   0

The call to a function succeeded.

#define NTAR_FAILURE   1

The call to a function failed for some reason.

#define NTAR_FAILURE_INVALID_ID   2

The identifier of a block or an option is not valid or unknown.

#define NTAR_FAILURE_FILENOTFOUND   3

The call to ntar_open failed because the file does not exist.

#define NTAR_FAILURE_FILEEXISTS   4

The call to ntar_open failed because the file does exist.

#define NTAR_FAILURE_CREATEFILEFAILED   5

The call to ntar_open failed because it was not possible to create the file.

#define NTAR_FAILURE_NOMEM   6

No memory is available to allocate the internal structures.

#define NTAR_FAILURE_SECTIONNOTCLOSED   7

An attempt to close a file or create a new section has been made without closing the current opened section.

#define NTAR_FAILURE_WRITEONREADFILE   8

An attempt to write on a read file has been made.

#define NTAR_FAILURE_IOWRITE   9

A request to write to file failed.

#define NTAR_FAILURE_BLOCKNOTCLOSED   10

An attempt to close a section failed because the current block has not been closed.

#define NTAR_FAILURE_IOREAD   11

A request to read from a file failed.

#define NTAR_FAILURE_EOF   12

A request to read from a file failed.

#define NTAR_FAILURE_INVALIDFILE   13

The file opened for reading is not a valid NTAR file.

#define NTAR_FAILURE_MALFORMED_BLOCK   14

The opened block is not correct (e.g. the block length at the end has not the same value as the one at the beginning).

#define NTAR_FAILURE_NOMOREBLOCKS   15

There are no more blocks in the current section.

#define NTAR_FAILURE_BLOCKDATAUNREAD   16

An attempt to read a block option has been made without previously reading the block data.

#define NTAR_FAILURE_SMALLBUFFER   17

The buffer passed to a function is too small to retrieve some info.

#define NTAR_FAILURE_BLOCKDATANOTSET   18

The block data passed to create a new block are NULL.

#define NTAR_FAILURE_DUPPTR   19

An attempt to add the same option structure to a block has been made.

#define NTAR_FAILURE_ASCIIDLFILE   20

The file was probably downloaded in FTP ASCII mode or another ASCII transfer mode.

#define NTAR_FAILURE_BLOCKTRAILERMISMATCH   21

The trailer block size does not match the header one. The block has been closed, however.

#define NTAR_FAILURE_ACCESSDENIED   22

An attempt to open a protected file (either in read or write mode) has been been without the proper credentials.

#define NTAR_FAILURE_BADFILEDESCRIPTOR   23

An attempt to read or write to an invalid file descriptor has been made by the library.

#define NTAR_FAILURE_INVALIDPARAMETER   24

A wrong parameter has been passed to a CRT function.

#define NTAR_FAILURE_TOOMANYOPENFILES   25

Too many open files. No more file descriptors are available, so no more files can be opened.

#define NTAR_FAILURE_DISKFULL   26

The disk is full, so any further writes to the file are not allowed.

#define NTAR_FAILURE_UNKNOWNERRNO   27

A CRT error has been detected by the library, but the corresponding errno code is unknown.

#define NTAR_FILEMODE_WRITE   0

The file was opened for writing new data to a new file.

#define NTAR_FILEMODE_READ   1

The file was opened for reading data.

#define NTAR_FILEMODE_CREATE   2

The file was opened for overwriting an existing file.

#define NTAR_FILEMODE_APPEND   3

The file was opened for appending to an existing file.

#define NTAR_OPEN_WRITE   "w"

Open an existing file and overwrite, or create a new one.

#define NTAR_OPEN_READ   "r"

Open an existing file for reading.

#define NTAR_OPEN_CREATE   "c"

Open a new file for writing.

#define NTAR_OPEN_APPEND   "a"

Open an existing file for appending new data.

Typedefs

typedef _ntar_option ntar_option

This structure represents an option of a block, at the user level.

typedef _ntar_block_handle ntar_block_handle

This structure represents a generic block contained in a section.

typedef _ntar_section_handle ntar_section_handle

This structure represents the root block for a file. It corresponds to a Section Header Block of the draft, see 3.1.

typedef _ntar_file_handle ntar_file_handle

This structure represents the handle to a dump file.

typedef int(* ntar_write_handler )(void *handle, void *buffer, size_t size)

This is the callback that is called when the library needs to write some data to the underlying storage. This callback should be defined when the storage (file, or memory) is opened (with ntar_open_by_handlers) in write mode.

typedef int(* ntar_read_handler )(void *handle, void *buffer, size_t size, size_t *read_bytes)

This is the callback that is called when the library needs to read some data from the underlying storage. This callback should be defined when the storage (file, or memory) is opened (with ntar_open_by_handlers) in read mode.

typedef int(* ntar_seek_handler )(void *handle, ntar_foff new_position, int origin, ntar_foff *pold_position)

This is the callback that is called when the library needs to obtain the current position in the file, and eventually seek to a new position. This callback is optional (both in read and write mode). Nonetheless, if this callback is not defined, not all the features of the library are available, in particular WRITE MODE

The section header block length is not written to file (the magic value 0xFFFFFFFFFFFFFFFF is written, instead). READ MODE
It is not possible to perform any backward seek in the file (i.e. only a sequential read of the trace file is possible).
Read operations can be slower, since the library uses empty reads to jump between blocks and sections.

typedef _ntar_file_handlers ntar_file_handlers

This structure contains the read/write/seek callbacks that ntar uses to manage an ntar file when the application provides its own read/write/seek functions to deal with the underlying storage.

Functions

int ntar_open (char *filename, char *flags, ntar_file_handle **pfile_handle)

This functions open a new dump file for reading or writing.

int ntar_open_by_handlers (ntar_file_handlers file_handlers, char *flags, ntar_file_handle **pfile_handle)

This functions open a new dump file for reading or writing using some external read/write/seek callbacks defined by the caller.

int ntar_close (ntar_file_handle *file_handle)

This function closes a dump file flushing all the unwritten data to disk.

int ntar_create_section (ntar_file_handle *file_handle, ntar_section_handle **psection_handle)

This function creates a new section (SHB as specified in 3.1 in the draft) into a dump file.

int ntar_close_section (ntar_section_handle *section_handle)

This function closes a section in a dump file, eventually flushing all the unsaved data to disk (if in write mode).

int ntar_add_section_option (ntar_section_handle *section_handle, ntar_option *option)

This function adds a new option value to a section.

int ntar_create_block (ntar_section_handle *section_handle, u_int32 block_type, void *data, ntar_block_handle **pblock_handle)

This function creates a new block into a section of a dump file.

int ntar_close_block (ntar_block_handle *block_handle)

This function closes a block in a dump file, eventually flushing all the unsaved data to disk (if in write mode).

int ntar_add_block_option (ntar_block_handle *block_handle, ntar_option *option)

This function adds a specified option value to a block handle.

int ntar_get_next_section (ntar_file_handle *file_handle, ntar_section_handle **psection_handle)

This function returns the next available section in a dump file.

int ntar_get_previous_section (ntar_file_handle *file_handle, ntar_section_handle **psection_handle)

This function returns the section in a dump file prior to the current one.

int ntar_get_section_options (ntar_section_handle *section_handle, ntar_option **options)

This function reads the option value of a given section in a dump file.

int ntar_get_next_block (ntar_section_handle *section_handle, ntar_block_handle **pblock_handle)

This function returns the next available block (excluding the SHB) in a section of a dump file.

int ntar_get_previous_block (ntar_section_handle *section_handle, ntar_block_handle **pblock_handle)

This function returns the block in a section of a dump file prior to the current one (excluding the SHB).

int ntar_get_block_type (ntar_block_handle *block_handle, u_int32 *pblock_type)

This function returns the block type of a given block.

int ntar_get_block_data (ntar_block_handle *block_handle, void **data)

This function retrieves the fixed data of a block.

int ntar_get_block_options (ntar_block_handle *block_handle, ntar_option **options)

This function reads all the options of a given block in a section.

int ntar_getversion (char *buffer, u_int32 *pbuffer_size)

This function returns the version of the library.


Defines
#define	NTAR_SUCCESS 0
	The call to a function succeeded.
#define	NTAR_FAILURE 1
	The call to a function failed for some reason.
#define	NTAR_FAILURE_INVALID_ID 2
	The identifier of a block or an option is not valid or unknown.
#define	NTAR_FAILURE_FILENOTFOUND 3
	The call to ntar_open failed because the file does not exist.
#define	NTAR_FAILURE_FILEEXISTS 4
	The call to ntar_open failed because the file does exist.
#define	NTAR_FAILURE_CREATEFILEFAILED 5
	The call to ntar_open failed because it was not possible to create the file.
#define	NTAR_FAILURE_NOMEM 6
	No memory is available to allocate the internal structures.
#define	NTAR_FAILURE_SECTIONNOTCLOSED 7
	An attempt to close a file or create a new section has been made without closing the current opened section.
#define	NTAR_FAILURE_WRITEONREADFILE 8
	An attempt to write on a read file has been made.
#define	NTAR_FAILURE_IOWRITE 9
	A request to write to file failed.
#define	NTAR_FAILURE_BLOCKNOTCLOSED 10
	An attempt to close a section failed because the current block has not been closed.
#define	NTAR_FAILURE_IOREAD 11
	A request to read from a file failed.
#define	NTAR_FAILURE_EOF 12
	A request to read from a file failed.
#define	NTAR_FAILURE_INVALIDFILE 13
	The file opened for reading is not a valid NTAR file.
#define	NTAR_FAILURE_MALFORMED_BLOCK 14
	The opened block is not correct (e.g. the block length at the end has not the same value as the one at the beginning).
#define	NTAR_FAILURE_NOMOREBLOCKS 15
	There are no more blocks in the current section.
#define	NTAR_FAILURE_BLOCKDATAUNREAD 16
	An attempt to read a block option has been made without previously reading the block data.
#define	NTAR_FAILURE_SMALLBUFFER 17
	The buffer passed to a function is too small to retrieve some info.
#define	NTAR_FAILURE_BLOCKDATANOTSET 18
	The block data passed to create a new block are NULL.
#define	NTAR_FAILURE_DUPPTR 19
	An attempt to add the same option structure to a block has been made.
#define	NTAR_FAILURE_ASCIIDLFILE 20
	The file was probably downloaded in FTP ASCII mode or another ASCII transfer mode.
#define	NTAR_FAILURE_BLOCKTRAILERMISMATCH 21
	The trailer block size does not match the header one. The block has been closed, however.
#define	NTAR_FAILURE_ACCESSDENIED 22
	An attempt to open a protected file (either in read or write mode) has been been without the proper credentials.
#define	NTAR_FAILURE_BADFILEDESCRIPTOR 23
	An attempt to read or write to an invalid file descriptor has been made by the library.
#define	NTAR_FAILURE_INVALIDPARAMETER 24
	A wrong parameter has been passed to a CRT function.
#define	NTAR_FAILURE_TOOMANYOPENFILES 25
	Too many open files. No more file descriptors are available, so no more files can be opened.
#define	NTAR_FAILURE_DISKFULL 26
	The disk is full, so any further writes to the file are not allowed.
#define	NTAR_FAILURE_UNKNOWNERRNO 27
	A CRT error has been detected by the library, but the corresponding errno code is unknown.
#define	NTAR_FILEMODE_WRITE 0
	The file was opened for writing new data to a new file.
#define	NTAR_FILEMODE_READ 1
	The file was opened for reading data.
#define	NTAR_FILEMODE_CREATE 2
	The file was opened for overwriting an existing file.
#define	NTAR_FILEMODE_APPEND 3
	The file was opened for appending to an existing file.
#define	NTAR_OPEN_WRITE "w"
	Open an existing file and overwrite, or create a new one.
#define	NTAR_OPEN_READ "r"
	Open an existing file for reading.
#define	NTAR_OPEN_CREATE "c"
	Open a new file for writing.
#define	NTAR_OPEN_APPEND "a"
	Open an existing file for appending new data.
Typedefs
typedef _ntar_option	ntar_option
	This structure represents an option of a block, at the user level.
typedef _ntar_block_handle	ntar_block_handle
	This structure represents a generic block contained in a section.
typedef _ntar_section_handle	ntar_section_handle
	This structure represents the root block for a file. It corresponds to a Section Header Block of the draft, see 3.1.
typedef _ntar_file_handle	ntar_file_handle
	This structure represents the handle to a dump file.
typedef int(*	ntar_write_handler )(void handle, void buffer, size_t size)
	This is the callback that is called when the library needs to write some data to the underlying storage. This callback should be defined when the storage (file, or memory) is opened (with ntar_open_by_handlers) in write mode.
typedef int(*	ntar_read_handler )(void handle, void buffer, size_t size, size_t *read_bytes)
	This is the callback that is called when the library needs to read some data from the underlying storage. This callback should be defined when the storage (file, or memory) is opened (with ntar_open_by_handlers) in read mode.
typedef int(*	ntar_seek_handler )(void handle, ntar_foff new_position, int origin, ntar_foff pold_position)
	This is the callback that is called when the library needs to obtain the current position in the file, and eventually seek to a new position. This callback is optional (both in read and write mode). Nonetheless, if this callback is not defined, not all the features of the library are available, in particular WRITE MODE The section header block length is not written to file (the magic value 0xFFFFFFFFFFFFFFFF is written, instead). READ MODE It is not possible to perform any backward seek in the file (i.e. only a sequential read of the trace file is possible). Read operations can be slower, since the library uses empty reads to jump between blocks and sections.
typedef _ntar_file_handlers	ntar_file_handlers
	This structure contains the read/write/seek callbacks that ntar uses to manage an ntar file when the application provides its own read/write/seek functions to deal with the underlying storage.
Functions
int	ntar_open (char filename, char flags, ntar_file_handle **pfile_handle)
	This functions open a new dump file for reading or writing.
int	ntar_open_by_handlers (ntar_file_handlers file_handlers, char flags, ntar_file_handle *pfile_handle)
	This functions open a new dump file for reading or writing using some external read/write/seek callbacks defined by the caller.
int	ntar_close (ntar_file_handle *file_handle)
	This function closes a dump file flushing all the unwritten data to disk.
int	ntar_create_section (ntar_file_handle file_handle, ntar_section_handle *psection_handle)
	This function creates a new section (SHB as specified in 3.1 in the draft) into a dump file.
int	ntar_close_section (ntar_section_handle *section_handle)
	This function closes a section in a dump file, eventually flushing all the unsaved data to disk (if in write mode).
int	ntar_add_section_option (ntar_section_handle section_handle, ntar_option option)
	This function adds a new option value to a section.
int	ntar_create_block (ntar_section_handle section_handle, u_int32 block_type, void data, ntar_block_handle **pblock_handle)
	This function creates a new block into a section of a dump file.
int	ntar_close_block (ntar_block_handle *block_handle)
	This function closes a block in a dump file, eventually flushing all the unsaved data to disk (if in write mode).
int	ntar_add_block_option (ntar_block_handle block_handle, ntar_option option)
	This function adds a specified option value to a block handle.
int	ntar_get_next_section (ntar_file_handle file_handle, ntar_section_handle *psection_handle)
	This function returns the next available section in a dump file.
int	ntar_get_previous_section (ntar_file_handle file_handle, ntar_section_handle *psection_handle)
	This function returns the section in a dump file prior to the current one.
int	ntar_get_section_options (ntar_section_handle section_handle, ntar_option *options)
	This function reads the option value of a given section in a dump file.
int	ntar_get_next_block (ntar_section_handle section_handle, ntar_block_handle *pblock_handle)
	This function returns the next available block (excluding the SHB) in a section of a dump file.
int	ntar_get_previous_block (ntar_section_handle section_handle, ntar_block_handle *pblock_handle)
	This function returns the block in a section of a dump file prior to the current one (excluding the SHB).
int	ntar_get_block_type (ntar_block_handle block_handle, u_int32 pblock_type)
	This function returns the block type of a given block.
int	ntar_get_block_data (ntar_block_handle block_handle, void *data)
	This function retrieves the fixed data of a block.
int	ntar_get_block_options (ntar_block_handle block_handle, ntar_option *options)
	This function reads all the options of a given block in a section.
int	ntar_getversion (char buffer, u_int32 pbuffer_size)
	This function returns the version of the library.