FBS_open.c File Reference

Universal can-opener to open FSW files. More...

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <fcntl.h>
#include <netdb.h>
#include <unistd.h>
#include <sys/stat.h>
#include <sys/types.h>
#include "PBI/Endianness.h"
#include "PBS/BSWP.ih"
#include "PBS/FFS.ih"
#include "PBS/INT.ih"
#include "ZLIB/zlib.h"
#include "MDB/MDB_pubdefs.h"
#include "FBS/FBS_msgs.h"
#include "FBS/FBS_pubrtos.h"
#include "FBS_mtx.ih"
#include "FBS_prvrtos.h"

Include dependency graph for FBS_open.c:


Data Structures
struct	_FILE_PrimaryHeader
	A description of the sacrosanct primary file header. More...
struct	_FILE_Stat
	Block of information associated with a file opened with FILE_open(). More...
Defines
#define	INT_FAKE_OK
	Allow unix to fake an interrupt lock.
#define	MKDIR(_a, _b) mkdir( _a, _b )
	Gloss over differences in the unix and VxWorks mkdir calls.
#define	FILE_K_HDR_SIZ (9)
	Number of bits used to descibe header size.
#define	FILE_K_HDR_RSV (3)
	Number of bits used (reserved).
#define	FILE_K_HDR_CMP (1)
	Number of bits used to descibe header compression.
#define	FILE_K_HDR_VER (3)
	Number of bits used to describe header version.
#define	FILE_V_HDR_SIZ ( 0 )
	Bit offset to header size field.
#define	FILE_V_HDR_RSV ( FILE_V_HDR_SIZ + FILE_K_HDR_SIZ )
	Bit offset to (reserved) field.
#define	FILE_V_HDR_CMP ( FILE_V_HDR_RSV + FILE_K_HDR_RSV )
	Bit offset to compression field.
#define	FILE_V_HDR_VER ( FILE_V_HDR_CMP + FILE_K_HDR_CMP )
	Bit offset to version field.
#define	FILE_M_HDR_SIZ (((1 << FILE_K_HDR_SIZ ) - 1) << FILE_V_HDR_SIZ )
	In place mask for the header size field.
#define	FILE_M_HDR_RSV (((1 << FILE_K_HDR_RSV ) - 1) << FILE_V_HDR_RSV )
	In place mask for the (reserved) field.
#define	FILE_M_HDR_CMP (((1 << FILE_K_HDR_CMP ) - 1) << FILE_V_HDR_CMP )
	In place mask for the compression field.
#define	FILE_M_HDR_VER (((1 << FILE_K_HDR_VER ) - 1) << FILE_V_HDR_VER )
	In place mask for the version field.
#define	FILE_K_BITALLOC (2)
	Number of unsigned ints used in bit allocation scheme.
#define	FILE_L_TEMPNAME (256)
	Maximum length of a temporary filename.
#define	FILE_ACS_SIZE (2048)
	Size of buffer to use during adler32 checksum verification.
Typedefs
typedef _FILE_PrimaryHeader	FILE_PrimaryHeader
	Typedef for struct _FILE_PrimaryHeader.
typedef _FILE_Stat	FILE_Stat
	Typedef for struct _FILE_Stat.
Functions
static unsigned int	FILE_inflate (int in, int out, unsigned int bufSize)
	File inflater.
static int	FILE_findSlot (int fd)
	Find the slot describing fd.
static void *	FILE_inflateAlloc (void *opaque, unsigned int numItems, unsigned int size)
	Memory allocation callback for ZLIB.
static unsigned int	FILE_inflateError (int errCode, const char func, const char msg)
	This function translates ZLIB native error codes into MSG codes.
static void	FILE_inflateFree (void opaque, void address)
	Memory free callback for ZLIB.
static char *	FILE_tempname (int idx, char *buf, unsigned int len)
	Generate a temporary file name.
int	FILE_close (int fd)
	Close a FSW file (regular, headed/not-headed, compressed/not-compressed).
unsigned int	FILE_decodePrimary (unsigned char buf, unsigned int len, unsigned int ver, unsigned int cmp, unsigned short typ, unsigned int key, unsigned int fcs)
	Assuming buf points to a file header, decode it.
unsigned int	FILE_getCompression (int fd)
	Get the compression flag associated with the file descriptor.
unsigned int	FILE_getKey (int fd)
	Get the value of the key associated with the file descriptor.
int	FILE_getName (int fd, char *nam, unsigned int len)
	Get the original file name associated with the file descriptor.
unsigned int	FILE_getSize (int fd)
	Get the file header size associated with the file descriptor.
unsigned short	FILE_getType (int fd)
	Get the value of the type associated with the file descriptor.
unsigned int	FILE_getVersion (int fd)
	Get the file header version associated with the file descriptor.
int	FILE_open (const char *fil, int flg, mode_t mod)
	Open a FSW file (regular, headed/not-headed, compressed/not-compressed).
Variables
static FBS_mti	mti
	Instance of (storage for) mutex (only used in Unix).
static volatile FBS_mtx	mtx
	Mutex to enforce serial open/close/delete operations on a single file.
static unsigned int	bookbits [FILE_K_BITALLOC]
	unsigned ints used in a bit allocation scheme to indicate booked slots
static FILE_Stat	bookslot [FILE_K_BITALLOC<< 5]
	Slots in which to remember file descriptors for "delete-on-close".
char	dir [] = { "/tmp/d000/" }
	Directory prefix for a temporary inflation file.

Detailed Description

Universal can-opener to open FSW files.

CVS $Id: FBS_open.c,v 1.4 2005/11/17 01:27:19 apw Exp $

Author:: A.P.Waite
D.Wood

Function Documentation

int FILE_close ( int fd )

Close a FSW file (regular, headed/not-headed, compressed/not-compressed).

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

0 Success

-1 Failure (use errno to retrieve further details)

FILE_close() is the complement to FILE_open(). The only value added of FILE_close() over close() is that FILE_close() will check the file descriptor of the file being closed, and if it corresponds to a temporary inflation file, it will delete the file.

unsigned int FILE_decodePrimary ( unsigned char * buf,

unsigned int len,

unsigned int * ver,

unsigned int * cmp,

unsigned short * typ,

unsigned int * key,

unsigned int * fcs

)

Assuming buf points to a file header, decode it.

Parameters:

buf (in) Pointer to buffer containing supposed file header

len (in) Length of buffer pointed to by buf

ver (out) Header version number (0 if no file header)

cmp (out) Header compression flag (0 if no file header)

typ (out) File type (0xffff if no file header)

key (out) File key (0xffffffff if no file header)

fcs (out) File body checksum (0xffffffff if no file header)

Return values:

0 The buffer does not contain a file header

x Offset in buf to where the file body begins

static int FILE_findSlot ( int fd ) [static]

Find the slot describing fd.

Parameters:

fd (in) File descriptor (conventional meaning)

Warning:
This routine has to scan a list in a potentially multi-threaded environment. To avoid mishaps, the search is performed under mutex. In the event of failure, the mutex is released. If successful, it is the responsibility of the calling routine to release the mutex.

Return values:

x Slot index of fd (and mutex is set).

-1 Failure (and mutex is released)

FILE_findSlot() scans the file information array maintained for files opened read-only by FILE_open(), with FSW headers (try saying that three times fast). If the file can be located, the index of the array slot is returned. If the file cannot be found, -1 is returned.

unsigned int FILE_getCompression ( int fd )

Get the compression flag associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

1 File compressed

0 File not compressed

FILE_getCompression() returns the compression bit from the FSW header of a file if:

The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value 0 is returned. Note that this is the compression bit from the original file open. If the original file is compressed, FILE_open() automatically runs a decompression step and points the caller to a decompressed version of the file.

unsigned int FILE_getKey ( int fd )

Get the value of the key associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

x Key value

-1 Failure (well OK, it's really 0xffffffff)

FILE_getKey() returns the key from the FSW header of a file if:

The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value 0xffffffff is returned.

int FILE_getName ( int fd,

char * nam,

unsigned int len

)

Get the original file name associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

nam (out) Buffer into which to place name

len (out) Maximum length of name buffer

Return values:

x True length of file name

-1 Failure (see below)

FILE_getName() returns the name of the file originally opened with FILE_open() if:

The nam pointer is not NULL
The len argument is greater than zero
The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value -1 is returned.
Assuming the above conditions are met, this routine will always return a zero terminated string in nam, even if nam is not sufficiently long to accomodate the full name. To check for this case, the caller should compare the string length of nam against the true name length, which is returned by this function.

unsigned int FILE_getSize ( int fd )

Get the file header size associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

x File header size

0 Guard value

FILE_getSize() returns the file header size from the FSW header of a file if:

The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value 0 is returned.
Note that the size returned is literally the number stored in the file header, and does not include the four bytes at the start of the header used to store the file header checksum.

unsigned short FILE_getType ( int fd )

Get the value of the type associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

x Type value

-1 Failure (well OK, it's really 0xffff)

FILE_getType() returns the type from the FSW header of a file if:

The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value 0xffff is returned.

unsigned int FILE_getVersion ( int fd )

Get the file header version associated with the file descriptor.

Parameters:

fd (in) File descriptor (conventional meaning)

Return values:

x Type value

0 Failure

FILE_getVersion() returns the file header version from the FSW header of a file if:

The file was opened with FILE_open()
The file was opened read-only
The file has a header

If these conditions are not met, the guard value 0 is returned.

static unsigned int FILE_inflate ( int in,

int out,

unsigned int bufSize

) [static]

File inflater.

Parameters:

in (in) Input file descriptor

out (in) Output file descriptor

bufSize (in) Buffer length

Returns:
x MSG code

static void * FILE_inflateAlloc ( void * prm,

unsigned int nitem,

unsigned int size

) [inline, static]

Memory allocation callback for ZLIB.

Parameters:

prm (in) Context parameter (unused)

nitem (in) Number of items to allocate.

size (in) Size (bytes) of each item.

Returns:
A pointer to the allocated memory, or NULL on failure.

static unsigned int FILE_inflateError ( int zcode,

const char * func,

const char * msg

) [static]

This function translates ZLIB native error codes into MSG codes.

Parameters:

zcode (in) The ZLIB error code.

func (in) The name of the function in which the error occurred.

msg (in) A message to print out in the MSG output.

Returns:
The MSG code value.

static void FILE_inflateFree ( void * prm,

void * add

) [inline, static]

Memory free callback for ZLIB.

Parameters:

prm (in) Context parameter (unused)

add (in) Address of memory to free

int FILE_open ( const char * fil,

int flg,

mode_t mod

)

Open a FSW file (regular, headed/not-headed, compressed/not-compressed).

Parameters:

fil (in) File name

flg (in) Open flags (O_RDONLY, O_WRONLY, O_RDWR, O_CREAT)

mod (in) Access mode (only used for NFS file creation)

Return values:

x File descriptor

-1 Failure

Warning:
If you open a file with FILE_open(), you must close it with FILE_close().
FILE_open() is designed to overlay the classic open() routine, adding the ability to deal with special format files peculiar to flight software. The call structure is identical to open(). If the open mode is O_WRONLY or O_RDWR, FILE_open() and open() are indistinguishable. If the open mode is O_RDONLY, things start to get exciting.
Flight software files appear in three different formats:

Regular file
Prefixed by a header, uncompressed
Prefixed by a header, compressed

When FILE_open() is asked to open any of these formats, it will first inspect the file to classify it. The adler32 checksum in the header is very powerful here. Subsequent processing depends on the file format:

Regular file. Indistinguishable from open() on the same file.
Prefixed by a header, uncompressed. The body of the file is adler32 check-summed. If it passes, the caller is returned a regular file descriptor with the file pointer pointing to the first byte past the header.
Prefixed by a header, compressed. The body of the file is adler32 check-summed. If it passes, the file is inflated in a temporary file (in /tmp/d000 on unix, in /ram/d000 in VxWorks). The original file is closed, the inflated file is opened O_RDONLY, and a file descriptor for the inflated file is returned to the caller. The temporary file is deleted when the file is closed (though the caller must use FILE_close() to close the file, not a simple close() call).

In keeping with the idea that FILE_open() is modeled on open(), the errno method is used to return extra information. One unusual feature of this is that errno can contain helpful information, even when the file open is successful.
If the return value is not -1 (i.e. the open succeeded), errno can contain:

FILE_S_SUCCESS Successfully opened a regular file, not in O_RDONLY mode
FILE_S_NOHED Successfully opened a regular file, in O_RDONLY mode
FILE_S_HEDNOCMP Successfully opened an uncompressed file with FSW header
FILE_S_HEDCMP Successfully opened a compressed file with FSW header

If the return value is -1 (i.e. the open failed), errno, in addition to any of the regular values that open() can return, can contain:

FILE_E_CORRUPT Adler32 of file body failed
FILE_E_NOMKDIR Could not make a temporary directory for inflation
FILE_E_NOSLOT Could not allocate a temporary file slot
FILE_E_NOTMPOPN Could not open the temporary file
FILE_E_NOINFLAT File inflation failed
FILE_E_NOREPOEN Could not reopen the temporary file after inflation

If you wish to use these values for additional checking, note that errno is a four byte word encoded as two two-byte units. The most significant unit is a module number and the lower unit is the "error" number. The additional error codes defined by FILE_open() are module 0x200 (to avoid collisions with unix and VxWorks error codes), and the error numbers obey MSG conventions, i.e. if the least significant bit is clear, the operation was a success.

static char * FILE_tempname ( int idx,

char * buf,

unsigned int len

) [inline, static]

Generate a temporary file name.

Parameters:

idx (in) Slot index of temporary file

buf (in) Buffer to write file name to

len (in) Maximum length of file name buffer

Returns:
Pointer to temporary file name string
FILE_tempname() constructs a file name algorithmically from the slot number assigned to the temporary file. The VxWorks name looks like a regular FSW embedded system name (albeit on the /ram disk). The unix file name is a little more elaborate (it includes host name and process number) to try to avoid collisions.

Generated on Wed Nov 16 20:49:52 2005 by

1.4.4

FBS_open.c File Reference

Data Structures

Defines

Typedefs

Functions

Variables

Detailed Description

Function Documentation