file_object.c File Reference

---

Detailed Description

Sharing of file descriptors through file objects.

Author:

Christian Biere

Date:

2006

#include "common.h"
#include "file_object.h"
#include "lib/atoms.h"
#include "lib/file.h"
#include "lib/iovec.h"
#include "lib/misc.h"
#include "lib/walloc.h"
#include "lib/override.h"

Data Structures
struct	file_object
Defines
#define	D(x)   &x, #x
Enumerations
enum	file_object_magic { FILE_OBJECT_MAGIC = 0xeb084325 }
Functions
gboolean	fd_is_writable (const int fd)
	Checks whether the given file descriptor is opened for write operations.
gboolean	fd_is_readable (const int fd)
	Checks whether the given file descriptor is opened for read operations.
gboolean	fd_is_readable_and_writable (const int fd)
	Checks whether the given file descriptor is opened for read and write operations.
gboolean	accmode_is_valid (const int fd, const int accmode)
	Checks whether the given file descriptor is compatible with given access mode.
void	file_object_check (const struct file_object *const fo)
	Applies some basic and fast consistency checks to a file object and causes an assertion failure if a check fails.
GHashTable *	file_object_mode_get_table (const int accmode)
	Get the hash table for a given access mode.
file_object *	file_object_find (const char *const pathname, int accmode)
	Find an existing file object associated with the given pathname for the given access mode.
file_object *	file_object_alloc (const int fd, const char *const pathname, int accmode)
void	file_object_remove (struct file_object *const fo)
void	file_object_free (struct file_object *const fo)
file_object *	file_object_open (const char *const pathname, int accmode)
	Acquires a file object for a given pathname and access mode.
file_object *	file_object_new (const int fd, const char *const pathname, int accmode)
	Acquires a new file object for a given pathname.
void	file_object_release (struct file_object **fo_ptr)
	Releases a file object and frees its memory.
void	file_object_revoke (const char *const pathname)
	Revokes all file objects associated with the pathname.
ssize_t	file_object_pwrite (const struct file_object *const fo, const void *const data, const size_t size, const filesize_t pos)
	Write the given data to a file object at the given offset.
ssize_t	file_object_pwritev (const struct file_object *const fo, const struct iovec *const iov, const int iov_cnt, const filesize_t pos)
	Write the given data to a file object at the given offset.
ssize_t	file_object_pread (const struct file_object *const fo, void *const data, const size_t size, const filesize_t pos)
	Read data from the file object from the given offset.
ssize_t	file_object_preadv (const struct file_object *const fo, struct iovec *const iov, const int iov_cnt, const filesize_t pos)
	Read data from a file object from the given offset.
int	file_object_get_fd (const struct file_object *const fo)
	Get the file descriptor associated with a file object.
const char *	file_object_get_pathname (const struct file_object *const fo)
	Get the pathname associated with a file object.
void	file_object_init (void)
	Initializes this module and must be called before using any other function of this module.
void	file_object_show_item (gpointer key, gpointer value, gpointer unused_udata)
void	file_object_destroy_table (GHashTable **ht_ptr, const char *const name)
void	file_object_close (void)
	Releases all used resources and should be called on shutdown.
Variables
GHashTable *	ht_file_objects_rdonly
GHashTable *	ht_file_objects_wronly
GHashTable *	ht_file_objects_rdwr

---

Define Documentation

#define D (  x   )     &x, #x

---

Enumeration Type Documentation

enum file_object_magic

Enumeration values: FILE_OBJECT_MAGIC

---

Function Documentation

gboolean accmode_is_valid (  const int  fd, const int  accmode )  [inline, static]

Checks whether the given file descriptor is compatible with given access mode. For example, if fd has access mode O_RDONLY but accmode is O_WRONLY or O_RDWR FALSE is returned, because the file descriptor is not writable. Parameters: fd  A valid file descriptor. Returns: TRUE if the file descriptor is compatible with the access mode.

gboolean fd_is_readable (  const int  fd  )  [inline, static]

Checks whether the given file descriptor is opened for read operations. Parameters: fd  A valid file descriptor. Returns: TRUE if the file descriptor is opened with O_RDONLY or O_RDWR.

gboolean fd_is_readable_and_writable (  const int  fd  )  [inline, static]

Checks whether the given file descriptor is opened for read and write operations. Parameters: fd  A valid file descriptor. Returns: TRUE if the file descriptor is opened with O_RDWR.

gboolean fd_is_writable (  const int  fd  )  [inline, static]

Checks whether the given file descriptor is opened for write operations. Parameters: fd  A valid file descriptor. Returns: TRUE if the file descriptor is opened with O_WRONLY or O_RDWR.

struct file_object* file_object_alloc (  const int  fd, const char *const   pathname, int  accmode )  [static]

void file_object_check (  const struct file_object *const   fo  )  [inline, static]

Applies some basic and fast consistency checks to a file object and causes an assertion failure if a check fails.

void file_object_close (  void   )

Releases all used resources and should be called on shutdown. Note: Still existing file objects are not destroyed.

void file_object_destroy_table (  GHashTable **  ht_ptr, const char *const   name )  [inline, static]

struct file_object* file_object_find (  const char *const   pathname, int  accmode )  [static]

Find an existing file object associated with the given pathname for the given access mode. Returns: If no file object with the given pathname is found NULL is returned.

void file_object_free (  struct file_object *const   fo  )  [static]

int file_object_get_fd (  const struct file_object *const   fo  )

Get the file descriptor associated with a file object. This should not be used lightly and the returned file descriptor should not be cached. Future versions might open/close the file descriptor on demand or dynamically. Parameters: An  initialized file object. Returns: The file descriptor of the file object.

const char* file_object_get_pathname (  const struct file_object *const   fo  )

Get the pathname associated with a file object. Parameters: An  initialized file object. Returns: The pathname of the file object.

void file_object_init (  void   )

Initializes this module and must be called before using any other function of this module.

GHashTable* file_object_mode_get_table (  const int  accmode  )  [inline, static]

Get the hash table for a given access mode. Returns: The hash table holding file object for the access mode.

struct file_object* file_object_new (  const int  fd, const char *const   pathname, int  accmode )

Acquires a new file object for a given pathname. There must not be any file object registered for this pathname already. Parameters: pathname  An absolute pathname. Returns: On failure NULL is returned. On success a file object is returned.

struct file_object* file_object_open (  const char *const   pathname, int  accmode )

Acquires a file object for a given pathname and access mode. If no matching file object exists, NULL is returned. Parameters: pathname  An absolute pathname. Returns: On failure NULL is returned. On success a file object is returned.

ssize_t file_object_pread (  const struct file_object *const   fo, void *const   data, const size_t  size, const filesize_t  pos )

Read data from the file object from the given offset. Parameters: fo  An initialized file object. data  A buffer for holding the data to be read. size  The amount of bytes to read (i.e., the size of data). offset  The file offset from which to start reading data. Returns: On failure -1 is returned and errno is set. On success the amount of bytes read is returned.

ssize_t file_object_preadv (  const struct file_object *const   fo, struct iovec *const   iov, const int  iov_cnt, const filesize_t  pos )

Read data from a file object from the given offset. Parameters: fo  An initialized file object. iov  An initialized I/O vector buffer. iov_cnt  The number of initialized buffer in iov (i.e., its size). offset  The file offset at which to start reading data. Returns: On failure -1 is returned and errno is set. On success the amount of data bytes read is returned.

ssize_t file_object_pwrite (  const struct file_object *const   fo, const void *const   data, const size_t  size, const filesize_t  pos )

Write the given data to a file object at the given offset. Parameters: fo  An initialized file object. data  An initialized buffer holding the data to write. size  The amount of bytes to write (i.e., the size of data). offset  The file offset at which to start writing the data. Returns: On failure -1 is returned and errno is set. On success the amount of bytes written is returned.

ssize_t file_object_pwritev (  const struct file_object *const   fo, const struct iovec *const   iov, const int  iov_cnt, const filesize_t  pos )

Write the given data to a file object at the given offset. Parameters: fo  An initialized file object. iov  An initialized I/O vector buffer. iov_cnt  The number of initialized buffer in iov (i.e., its size). offset  The file offset at which to start writing the data. Returns: On failure -1 is returned and errno is set. On success the amount of data bytes written is returned.

void file_object_release (  struct file_object **  fo_ptr  )

Releases a file object and frees its memory. The underlying file descriptor however is not closed unless no other file object references it. The pointer is nullified. Parameters: fo_ptr  If pointing to NULL, nothing happens. Otherwise, it must point to an initialized file_object.

void file_object_remove (  struct file_object *const   fo  )  [static]

void file_object_revoke (  const char *const   pathname  )

Revokes all file objects associated with the pathname. This is useful after moving a file to prevent that file_object_open() returns a file object associated with the now removed file. Parameters: pathname  An absolute pathname.

void file_object_show_item (  gpointer  key, gpointer  value, gpointer  unused_udata )  [static]

---

Variable Documentation

GHashTable* ht_file_objects_rdonly [static]

Note: NOTE: It is the callers responsibility to ensure consistency between the file descriptor and the pathname. Thus, this must not be used with arbitrary paths but only for directories under our control. For example, the file could be removed by another process and file_object_open() would return the file descriptor of the already removed file. When the last file object for this pathname is released, the file contents would be lost. Likewise, you can open a file that has already been deleted or moved when using file_object_open(). Whether the file still exists can be checked with fstat(). However this is not necessarily the same file referenced by the file object. The current offset is shared that means, you should always use pread() instead of read(), pwrite() instead of write() etc. The replacement functions do not restore the original file offset and they are NOT thread-safe. As gtk-gnutella is mono-threaded this should never be a problem. The file objects created with O_RDWR are returned for all file_object_open() requests. That means the caller must take care to not accidently write to a file object acquired with O_RDONLY. Normally, file objects should be acquired as follows: // Try to reuse an existing file object file = file_object_open(pathname, mode); if (!file) { int fd; // If none exists, create a new file object fd = open_the_file(pathname, mode); if (fd >= 0) { file = file_object_new(fd, pathname, mode); } } if (!file) { // Error handling } If a file object is created and released in the same function i.e., reuse unlikely, the strictest access mode should be used (O_RDONLY or O_WRONLY). Otherwise, it is best to use O_RDWR so that the same object can be reused by further calls to file_object_open() whilst the object exists. This API does not allow opening the same file twice for compatible access modes. You can create one file object for O_RDONLY and another with O_WRONLY for the same path though, if none with O_RDWR exists.

GHashTable* ht_file_objects_rdwr [static]

GHashTable* ht_file_objects_wronly [static]

---