bin.h File Reference

Data Structures
struct	header_t
union	header_t.__unnamed__

Macros
#define	M_INT   M_INT32
#define	M_STR   M_INT8
#define	M_SPINT   M_INT
#define	M_DSP   M_DSP32
#define	M_CSP   M_CSP32
#define	M_SSP   M_SSP32
#define	M_ZSP   M_ZSP32
#define	IS_SHM(name)   (name && ((name[0]=='/' && !strchr(name+1, '/')) || !mystrcmp(name, "/shm")))

Typedefs
typedef int	spint

Enumerations
enum	M_ID {   M_0 =0x0, M_CSP64 =0x6400, M_DSP64 =0x6401, M_DBL =0x6402,   M_INT64 =0x6403, M_CMP =0x6404, M_INT32 =0x6405, M_CSP32 =0x6406,   M_DSP32 =0x6407, M_FLT =0x6408, M_ZMP =0x6409, M_INT8 =0x640A,   M_INT16 =0x640B, MCC_ANY =0x6421, M_SSP64 =0x6430, M_SSP32 =0x6431,   M_ZSP64 =0x6432, M_ZSP32 =0x6433, M_COMMENT =0x6500, M_SKIP =0x6600,   M_MAP32 =0x016408, M_RECTMAP32 =0x026408, M_LOC32 =0x036408, M_MAP64 =0x016402,   M_RECTMAP64 =0x026402, M_LOC64 =0x036402, M_EOD =0x64FF }

Functions
int	zfexist (const char *format,...)
	saving to disk will be disabled when set to nonzero. More...
void	zftouch (const char *format,...)
int	zfeof (file_t *fp)
long	zfpos (file_t *fp)
long	zfseek (file_t *fp, long offset, int whence)
void	zfrewind (file_t *fp)
long	zflen (file_t *fp)
file_t *	zfopen (const char *fn, const char *mod)
file_t *	zfdopen (int fd)
const char *	zfname (file_t *fp)
int	zfisfits (file_t *fp)
void	zfclose (file_t *fp)
int	zfwrite (const void *ptr, const size_t size, const size_t nmemb, file_t *fp)
int	zfread (void *ptr, const size_t size, const size_t nmemb, file_t *fp)
int	zferrno (file_t *fp)
uint64_t	bytes_header (const char *keywords)
void	write_timestamp (file_t *fp)
void	write_header (const header_t *header, file_t *fp)
int	read_header (header_t *header, file_t *fp)
long	writearr (const void *fpn, const int isfile, const size_t size, const uint32_t magic, const char *keywords, const void *p, const uint64_t nx, const uint64_t ny)
struct mem_t *	mem_new (void *p) __attribute__((warn_unused_result))
void	mem_unref (mem_t **in)
mem_t *	mem_ref (mem_t *in) __attribute__((warn_unused_result))
void	mem_replace (mem_t *in, void *p)
int	mem_nref (const mem_t *in)
void *	mem_p (const mem_t *in)
mem_t *	mmap_open (const char *fn, size_t msize, int rw)
void	mmap_write_header (char **p0, uint32_t magic, long nx, long ny, const char *keywords)
void	mmap_read_header (char **p0, uint32_t *magic, long *nx, long *ny, const char **pkeywords)
async_t *	async_init (file_t *fp, const size_t size, const uint32_t magic, const char *str, const void *p, const uint64_t nx, const uint64_t ny)
void	async_write (async_t *async, long offset, int wait)
void	async_free (async_t *async)

Detailed Description

Defines our custom file format .bin that may be gzipped and the basic IO functions. All file read/write operators are through functions in this file. The routines can also operate on .fits files.

---

Data Structure Documentation

header_t

struct header_t

Collaboration diagram for header_t:

Data Fields
union header_t	__unnamed__
uint64_t	nx
uint64_t	ny
char *	str

header_t.__unnamed__

union header_t.__unnamed__

Collaboration diagram for header_t.__unnamed__:

Data Fields
M_ID	id
uint32_t	magic

Function Documentation

zfexist()

int zfexist	(	const char *	format,
			...
	)

saving to disk will be disabled when set to nonzero.

Test whether a bin file exist.

zftouch()

void zftouch	(	const char *	format,
			...
	)

Update the modification time of a bin file.

zfeof()

int zfeof

(

file_t *

fp

)

Return 1 if end of file is reached.

zfpos()

long zfpos

(

file_t *

fp

)

Tell position pointer in file.

zfseek()

long zfseek	(	file_t *	fp,
		long	offset,
		int	whence
	)

Move the current position pointer, like fseek

zfrewind()

void zfrewind

(

file_t *

fp

)

Move the file position pointer to the beginning

zflen()

long zflen

(

file_t *

fp

)

Return file length

zfopen()

file_t* zfopen	(	const char *	fni,
		const char *	mod
	)

Open a bin file for read/write access.

Whether the file is gzipped or not is automatically determined when open for reading. When open for writing, if the file name ends with .bin or .fits, will not be gzipped. If the file has no suffix, the file will be gzipped and .bin is appened to file name.

zfname()

const char* zfname

(

file_t *

fp

)

Open a bin file or socket for read/write access.

Whether the file is gzipped or not is automatically determined when open for reading. When open for writing, if the file name ends with .bin or .fits, will not be gzipped. If the file has no suffix, the file will be gzipped and .bin is appened to file name. Return the underlining filename

zfisfits()

int zfisfits

(

file_t *

fp

)

Return 1 when it is a fits file.

zfclose()

void zfclose

(

file_t *

fp

)

Close the file.

zfwrite()

int zfwrite	(	const void *	ptr,
		const size_t	size,
		const size_t	nmemb,
		file_t *	fp
	)

Handles byteswapping in fits file format then call zfwrite_do to do the actual writing.

zfread()

int zfread	(	void *	ptr,
		const size_t	size,
		const size_t	nmemb,
		file_t *	fp
	)

Handles byteswapping in fits file format then call zfread_do to do the actual writing. return 0 when succeed and -1 when error.

zferrno()

int zferrno

(

file_t *

fp

)

Return the error number

bytes_header()

uint64_t bytes_header

(

const char *

keywords

)

Get the length of mem to storge the header and its dimension, rounded to multiple of 8.

write_header()

void write_header	(	const header_t *	header,
		file_t *	fp
	)

A unified header writing routine for .bin and .fits files. It write the array information and string header if any.

read_header()

int read_header	(	header_t *	header,
		file_t *	fp
	)

A unified header reading routine for .bin and .fits files. It read the array information and string header if any. Return non zero value if reading failed

writearr()

long writearr	(	const void *	fpn,
		const int	isfn,
		const size_t	size,
		const uint32_t	magic,
		const char *	str,
		const void *	p,
		const uint64_t	nx,
		const uint64_t	ny
	)

Check whether the header refers to a cell. If yes, return NULL. nx, ny are assigned to the dimension.

Write the time stamp as header into current location in the file. Write an 1-d or 2-d array into the file. First write a magic number that represents the data type. Then write two numbers representing the dimension. Finally write the data itself.

returns the file offset of the array start

Parameters

[in]	fpn	The file pointer
[in]	isfn	Is this a filename or already opened file
[in]	size	Size of each element
[in]	magic	The magic number. see bin.h
[in]	str	The header as string
[in]	p	The data of the array
[in]	nx	Number of rows. this index changes fastest
[in]	ny	Number of columns. 1 for vector

mem_new()

struct mem_t* mem_new

(

void *

p

)

Create a mem_t object.

Notice that nref is set to 0. Default is set to reference heap memory.

mem_unref()

void mem_unref

(

mem_t **

pin

)

Unreference the mmaped memory. When the reference drops to zero free or unmap it.

mem_ref()

mem_t* mem_ref

(

mem_t *

in

)

Add a reference to a mem_t.

mem_replace()

void mem_replace	(	mem_t *	in,
		void *	p
	)

Replace internal vector. If p is null, checking only. Use with care.

mem_nref()

int mem_nref

(

const mem_t *

in

)

Check whether it is a referenced data.

mem_p()

void* mem_p

(

const mem_t *

in

)

Return internal pointer

mmap_open()

mem_t* mmap_open	(	const char *	fn,
		size_t	msize,
		int	rw
	)

Open a file for write with mmmap. We don't provide an access control here for generic usage of the function. Lock on a special dummy file for access control.

mmap_write_header()

void mmap_write_header	(	char **	p0,
		uint32_t	magic,
		long	nx,
		long	ny,
		const char *	keywords
	)

Initialize the header in the mmaped file. If header is not null, header0 points to its location in mmaped file. Upon exit, p0 points to the location of data p.

mmap_read_header()

void mmap_read_header	(	char **	p0,
		uint32_t *	magic,
		long *	nx,
		long *	ny,
		const char **	pkeywords
	)

Initialize the dimension from the header in the mmaped file.

async_init()

async_t* async_init	(	file_t *	fp,
		const size_t	size,
		const uint32_t	magic,
		const char *	str,
		const void *	p,
		const uint64_t	nx,
		const uint64_t	ny
	)

Allocates space in fp for our block of data by writing header first and skip to the end of data offset. It has the same interface as writearr except only fp is allowed Use aio_* api if USE_ASYNC is set, otherwise use pwrite() aio_* api launches threads for async writing. pwrite is much simpler for our usecase. There is no impact on simulation step timing. we don't use mmap to write to file as it causes excessive traffic to NFS file system.

async_write()

void async_write	(	async_t *	async,
		long	offset,
		int	wait
	)

Wait until previous async write are finished. Write to file asynchronously. offset is the end of block that is ready to write.