backend/file.h File Reference

---

Detailed Description

File management Handling Files is splitted into different classes: 1.

The 'lumiera_file' class which acts as interface to the outside for managing files. 'lumiera_file' is addressed by the name of the file. Since files can have more than one name (hardlinks) many 'lumiera_file' can point to a single 'lumiera_filedescriptor' 2. The 'lumiera_filedescriptor' class which does the real work managing the file in the back. 3. Since OS-filehandles are a limited resource we access the lazily as 'lumiera_filehandle' which are managed in a 'lumiera_filehandlecache'

Definition in file file.h.

#include "lib/mutex.h"
#include "lib/llist.h"
#include "lib/error.h"
#include "backend/filehandle.h"
#include "backend/filedescriptor.h"

Include dependency graph for file.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	lumiera_file_struct
Defines
#define	LUMIERA_FILE_CREATE   (O_RDWR | O_LARGEFILE | O_NOATIME | O_CREAT | O_EXCL)
#define	LUMIERA_FILE_MASK   ~(O_CREAT | O_EXCL | O_TRUNC)
#define	LUMIERA_FILE_READONLY   (O_RDONLY | O_LARGEFILE | O_NOATIME)
#define	LUMIERA_FILE_READWRITE   (O_RDWR | O_LARGEFILE | O_NOATIME)
#define	LUMIERA_FILE_RECREATE   (O_RDWR | O_LARGEFILE | O_NOATIME | O_CREAT | O_TRUNC)
Typedefs
typedef struct lumiera_file_struct	lumiera_file
typedef lumiera_file *	LumieraFile
Functions
	LUMIERA_ERROR_DECLARE (FILE_CHANGED)
void	lumiera_file_delete (LumieraFile self)
	Frees a file structure.
LumieraFile	lumiera_file_destroy (LumieraFile self)
	Destroy a file structure.
int	lumiera_file_handle_acquire (LumieraFile self)
	Get a POSIX filehandle for a file.
void	lumiera_file_handle_release (LumieraFile self)
	Put filehandle back into cache aging.
LumieraFile	lumiera_file_init (LumieraFile self, const char *name, int flags)
	Initialize a file structure.
LumieraFile	lumiera_file_new (const char *name, int flags)
	Allocate a new file structure.
	NOBUG_DECLARE_FLAG (file)

---

Function Documentation

LumieraFile lumiera_file_init	(	LumieraFile	self,
		const char *	name,
		int	flags
	)

Initialize a file structure.

Parameters:

	self	pointer to the file structure
	name	filename
	flags	open flags

Returns:

self

Definition at line 38 of file file.c.

{
  TRACE (file);
  if (!(self->descriptor = lumiera_filedescriptor_acquire (name, flags)))
    return NULL;
  self->name = lumiera_strndup (name, PATH_MAX);

  return self;
}

LumieraFile lumiera_file_destroy

(

LumieraFile

self

)

Destroy a file structure.

frees all associated resources, releases the filedescriptor etc.

Parameters:

self

file structure to be destroyed

Returns:

self

Definition at line 49 of file file.c.

References lumiera_free().

{
  TRACE (file);
  lumiera_filedescriptor_release (self->descriptor);
  lumiera_free (self->name);
  return self;
}

Here is the call graph for this function:

LumieraFile lumiera_file_new	(	const char *	name,
		int	flags
	)

Allocate a new file structure.

Parameters:

	name	filename
	flags	open flags

Returns:

new file structure

Definition at line 59 of file file.c.

{
  TRACE (file);
  LumieraFile self = lumiera_malloc (sizeof (lumiera_file));
  return lumiera_file_init (self, name, flags);
}

void lumiera_file_delete

(

LumieraFile

self

)

Frees a file structure.

Parameters:

self

file structure to be freed

Definition at line 67 of file file.c.

References lumiera_free().

{
  TRACE (file);
  lumiera_free (lumiera_file_destroy (self));
}

Here is the call graph for this function:

int lumiera_file_handle_acquire

(

LumieraFile

self

)

Get a POSIX filehandle for a file.

Filehandles are opened on demand and must be acquired for use. Using filehandles is refcounted and might be nested. After using them they must be released which puts them back into filehandlecache aging.

Parameters:

self

file structure

Returns:

POSIX filehandle or -1 on error, check lumiera_error() to retrieve the errorcode Currently only LUMIERA_ERROR_ERRNO will be raised but this might change in future. Opening files can fail for many reasons and at any time!

Definition at line 75 of file file.c.

References LUMIERA_ERROR_SET, and LUMIERA_MUTEX_SECTION.

{
  TRACE (file);
  REQUIRE (self);
  REQUIRE (self->descriptor);
  REQUIRE (lumiera_fhcache);

  LUMIERA_MUTEX_SECTION (file, &self->descriptor->lock)
    {
      if (!self->descriptor->handle)
        /* no handle yet, get a new one */
        lumiera_filehandlecache_handle_acquire (lumiera_fhcache, self->descriptor);
      else
        lumiera_filehandlecache_checkout (lumiera_fhcache, self->descriptor->handle);

      if (self->descriptor->handle->fd == -1)
        {
          int fd;
          fd = open (self->name, self->descriptor->flags & LUMIERA_FILE_MASK);
          if (fd == -1)
            {
              LUMIERA_ERROR_SET (file, ERRNO);
            }
          else
            {
              struct stat st;
              if (fstat (fd, &st) == -1)
                {
                  close (fd);
                  LUMIERA_ERROR_SET (file, ERRNO);
                }
              else if (self->descriptor->stat.st_dev != st.st_dev || self->descriptor->stat.st_ino != st.st_ino)
                {
                  close (fd);
                  /* Woops this is not the file we expected to use */
                  LUMIERA_ERROR_SET (file, FILE_CHANGED);
                }
            }
          self->descriptor->handle->fd = fd;
        }
    }

  return self->descriptor->handle->fd;
}

void lumiera_file_handle_release

(

LumieraFile

self

)

Put filehandle back into cache aging.

Parameters:

self

file which handle to be released

Definition at line 122 of file file.c.

References LUMIERA_MUTEX_SECTION.

{
  TRACE (file);

  LUMIERA_MUTEX_SECTION (file, &self->descriptor->lock)
    {
      lumiera_filehandlecache_checkin (lumiera_fhcache, self->descriptor->handle);
    }
}