Exported functions


Functions

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_add_section_option (ntar_section_handle *section_handle, ntar_option *option)
 This function adds a new option value to a section.
int ntar_close (ntar_file_handle *file_handle)
 This function closes a dump file flushing all the unwritten data to disk.
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_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_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_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_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_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_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_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_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_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_getversion (char *buffer, u_int32 *pbuffer_size)
 This function returns the version of the library.
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.

Function Documentation

int ntar_add_block_option (  ntar_block_handle *  block_handle,
ntar_option *  option
) 
 

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

Parameters:
block_handle HAndle to the block we want to add an option
option Pointer to a ntar_structure containing all the data of the option.
Returns:

Todo:
Because of a limit of the current ntar engine, all the options are saved to disk when the block is closed. As a consequence, the option pointer, as well as all the data stored in it, must remain valid and unmodified until the block is closed.
Examples:
test005.c, test006.c, test007.c, test012.c, and test014.c.

int ntar_add_section_option (  ntar_section_handle *  section_handle,
ntar_option *  option
) 
 

This function adds a new option value to a section.

Note:
It's not possible to set an option if the dump file was opened in read mode.
Parameters:
section_handle Handle to the target section.
option Pointer to a ntar_structure containing all the data of the option.
Returns:

Todo:
Because of a limit of the current ntar engine, all the options are saved to disk when the section is closed. As a consequence, the option pointer, as well as all the data stored in it, must remain valid and unmodified until the section is closed.
Examples:
test004.c, and test012.c.

int ntar_close (  ntar_file_handle *  file_handle  ) 
 

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

Parameters:
file_handle Handle to the dump file to be closed.
Returns:

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).

Parameters:
block_handle Handle to the block that must be closed.
Returns:
Examples:
test002.c, test003.c, test007.c, test008.c, test009.c, test013.c, test017.c, and test018.c.

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).

Parameters:
section_handle Section that must be closed.
Returns:
Examples:
test001.c, test015.c, test016.c, and test017.c.

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.

Note:
It's not possible to create a new block if the dump file was opened in read mode.
Parameters:
section_handle Handle to the section that will contain the new block.
block_type Id of the block that should be created
data Pointer to the header value thatt should be set in the block handle.
pblock_handle Address of a user allocated pointer that will be filled with the handle of the newly created block.
Returns:
Examples:
test002.c, test003.c, test005.c, test006.c, test007.c, test014.c, and test017.c.

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.

Note:
It's not possible to create a new section if the dump file was opened in read mode.
Parameters:
file_handle handle to the dump file.
psection_handle Address of a user allocated pointer that will be filled with an handle to the newly created section.
Returns:
Examples:
test001.c, test002.c, test003.c, test004.c, test005.c, test006.c, test007.c, test012.c, test014.c, and test017.c.

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

This function retrieves the fixed data of a block.

Parameters:
block_handle Handle to the block.
data Address of a user allocated pointer that will be filled with the block data.
Note:
The data retrieved with this function (in parameter data) should NOT be freed, and remain valid up to the next call to ntar_get_block_data or ntar_close_block, whatever comes first.
Returns:
Examples:
test010.c, test011.c, and test013.c.

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.

Parameters:
block_handle Handle to the block.
options Address of a user allocated pointer to a ntar_structure that will be filled with the head of a list containing all the options of the block.
Returns:
Note:
This function will fail with error code NTAR_FAILURE_BLOCKDATAUNREAD if the function ntar_get_block_data has not been called previously on the same block_handle.

int ntar_get_block_type (  ntar_block_handle *  block_handle,
u_int32 *  pblock_type
) 
 

This function returns the block type of a given block.

Parameters:
block_handle Handle to the block
pblock_type Pointer to an integer that will be filled with the block type of the current block.
Returns:
Examples:
test010.c, test011.c, and test013.c.

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.

Note:
This function fails if the file was not opened in read mode.
Parameters:
section_handle Handle to a section of a dump file.
pblock_handle Address of a user allocated pointer that will be filled with an handle to the next block.
Returns:
Note:
If there are no more blocks, this function returns NTAR_FAILURE_NOMOREBLOCKS
Examples:
test008.c, test009.c, test010.c, test011.c, test013.c, and test018.c.

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.

Note:
This function fails if the file was not opened in read mode.
Parameters:
file_handle Handle to the dump file.
psection_handle Address of a user allocated pointer that will be filled with an handle to the next section.
Returns:
Note:
If there are no more sections, this function returns NTAR_FAILURE_EOF
Examples:
test008.c, test009.c, test010.c, test011.c, test013.c, test015.c, test016.c, and test018.c.

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).

Note:
This function fails if the file was not opened in read mode.
Parameters:
section_handle Handle to a section of a dump file.
pblock_handle Address of a user allocated pointer that will be filled with an handle to the previous block.
Returns:
Note:
If there are no more blocks, this function returns NTAR_FAILURE_NOMOREBLOCKS

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.

Note:
This function fails if the file was not opened in read mode.
Parameters:
file_handle Handle to the dump file.
psection_handle Address of a user allocated pointer that will be filled with an handle to the previous section.
Returns:
Note:
If there are no more sections, this function returns NTAR_FAILURE_NOMOREBLOCKS
Todo:
At the moment it's not implemented nor exported

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.

Parameters:
section_handle Handle to the section.
options Address of a user allocated pointer to a ntar_structure that will be filled with the head of a list containing all the options of the section.
Returns:
Note:
The data retrieved with this function (in parameter data) should NOT be freed, and remain valid up to the next call to ntar_get_section_options or ntar_close_section, whatever comes first.
Examples:
test011.c, test015.c, and test016.c.

int ntar_getversion (  char *  buffer,
u_int32 *  pbuffer_size
) 
 

This function returns the version of the library.

Parameters:
buffer Pointer to a user allocate buffer that will be filled with a NULL terminated string representing the version of the library.
pbuffer_size Pointer to a user allocated unsigned integer. On input, it should contain the length of the buffer. If the buffer is too small, this function returns NTAR_FAILURE_SMALLBUFFER. On output, if the function is successful it contains the number of used bytes in the buffer, if the buffer is too small it returns the number of needed bytes to return the library version. In order to retrieve the number of needed bytes, it is possible to set buffer to NULL, and buffer_size to 0. The function will return NTAR_FAILURE_SMALLBUFFER and pbuffer_size will contain the number of needed bytes.
Note:
The suggested pattern to call this function is the following one 
    char *buffer;
    u_int32 buffer_size;

    buffer_size = 0;

    if (ntar_getversion(NULL, &buffer_size) != NTAR_FAILURE_SMALLBUFFER)
    {
        ...some failure occurred...
    }

    buffer = (char*)malloc(buffer_size);
    ...add check for failed malloc...

    if (ntar_getversion(buffer, &buffer_size) != NTAR_SUCCESS)
    {
        ...some failure occurred...
    }
    else
        printf("NTAR version: %s\n", buffer);
Returns:

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

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

Parameters:
filename Name of the file to be opened.
flags The opening mode of the file. At the moment the accepted values are
  • "r" to read the file
  • "w" to write a new file. If the file exists, the file is overwritten.
  • "a" to append a new capture to an existing file.
  • "c" to write a new file. If the file exists, the function fails.
pfile_handle Address of a user allocated pointer that will be filled with the handle to a dump file.
Returns:
Examples:
test001.c, test002.c, test003.c, test004.c, test005.c, test006.c, test007.c, test008.c, test009.c, test010.c, test011.c, test012.c, test013.c, test014.c, test015.c, and test016.c.

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.

Parameters:
file_handlers Structure containing the file handlers that the library will use to read or write the trace file. All the pointers contained in this structure should remain valid until the file is closed with ntar_close.
flags The opening mode of the file. At the moment the accepted values are
pfile_handle Address of a user allocated pointer that will be filled with the handle to a dump file.
Returns:

Todo:
The flags are completely nonsense. What is the meaning of appending when the user provides the callbacks??

NTAR documentation. Copyright (c) 2004 - 2005 Condor Engineering, Inc. All rights reserved.