X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_disk_lib.h;h=340c35a4e5cb8019cc0639b098f3042f230f2f4d;hb=f9b7adcad3cc030a800cbc9a96709454c45ae06f;hp=3886be7c9f20d55c9b85d3539978121ffeb5951b;hpb=0a217a8df1657b4334b55b0e4a6c7837a8dbcfd9;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_disk_lib.h b/src/include/gnunet_disk_lib.h index 3886be7c9..340c35a4e 100644 --- a/src/include/gnunet_disk_lib.h +++ b/src/include/gnunet_disk_lib.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2001, 2002, 2003, 2004, 2005, 2006 Christian Grothoff (and other contributing authors) + (C) 2001, 2002, 2003, 2004, 2005, 2006, 2009 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -22,18 +22,27 @@ * @file include/gnunet_disk_lib.h * @brief disk IO apis */ - #ifndef GNUNET_DISK_LIB_H #define GNUNET_DISK_LIB_H -#include "gnunet_configuration_lib.h" -#include "gnunet_scheduler_lib.h" +/** + * Opaque handle used to access files. + */ +struct GNUNET_DISK_FileHandle; + +/** + * Handle used to manage a pipe. + */ +struct GNUNET_DISK_PipeHandle; + /* we need size_t, and since it can be both unsigned int or unsigned long long, this IS platform dependent; but "stdlib.h" should be portable 'enough' to be unconditionally available... */ #include +#include "gnunet_configuration_lib.h" +#include "gnunet_scheduler_lib.h" #ifdef __cplusplus extern "C" @@ -43,6 +52,166 @@ extern "C" #endif #endif + +/** + * Specifies how a file should be opened. + */ +enum GNUNET_DISK_OpenFlags + { + + /** + * Open the file for reading + */ + GNUNET_DISK_OPEN_READ = 1, + + /** + * Open the file for writing + */ + GNUNET_DISK_OPEN_WRITE = 2, + + /** + * Open the file for both reading and writing + */ + GNUNET_DISK_OPEN_READWRITE = 3, + + /** + * Fail if file already exists + */ + GNUNET_DISK_OPEN_FAILIFEXISTS = 4, + + /** + * Truncate file if it exists + */ + GNUNET_DISK_OPEN_TRUNCATE = 8, + + /** + * Create file if it doesn't exist + */ + GNUNET_DISK_OPEN_CREATE = 16, + + /** + * Append to the file + */ + GNUNET_DISK_OPEN_APPEND = 32 + }; + +/** + * Specifies what type of memory map is desired. + */ +enum GNUNET_DISK_MapType + { + /** + * Read-only memory map. + */ + GNUNET_DISK_MAP_TYPE_READ = 1, + + /** + * Write-able memory map. + */ + GNUNET_DISK_MAP_TYPE_WRITE = 2, + /** + * Read-write memory map. + */ + GNUNET_DISK_MAP_TYPE_READWRITE = 3 + }; + + +/** + * File access permissions, UNIX-style. + */ +enum GNUNET_DISK_AccessPermissions + { + /** + * Nobody is allowed to do anything to the file. + */ + GNUNET_DISK_PERM_NONE = 0, + + /** + * Owner can read. + */ + GNUNET_DISK_PERM_USER_READ = 1, + + /** + * Owner can write. + */ + GNUNET_DISK_PERM_USER_WRITE = 2, + + /** + * Owner can execute. + */ + GNUNET_DISK_PERM_USER_EXEC = 4, + + /** + * Group can read. + */ + GNUNET_DISK_PERM_GROUP_READ = 8, + + /** + * Group can write. + */ + GNUNET_DISK_PERM_GROUP_WRITE = 16, + + /** + * Group can execute. + */ + GNUNET_DISK_PERM_GROUP_EXEC = 32, + + /** + * Everybody can read. + */ + GNUNET_DISK_PERM_OTHER_READ = 64, + + /** + * Everybody can write. + */ + GNUNET_DISK_PERM_OTHER_WRITE = 128, + + /** + * Everybody can execute. + */ + GNUNET_DISK_PERM_OTHER_EXEC = 256 + }; + + +/** + * Constants for specifying how to seek. + */ +enum GNUNET_DISK_Seek + { + /** + * Seek an absolute position (from the start of the file). + */ + GNUNET_DISK_SEEK_SET, + + /** + * Seek a relative position (from the current offset). + */ + GNUNET_DISK_SEEK_CUR, + + /** + * Seek an absolute position from the end of the file. + */ + GNUNET_DISK_SEEK_END + }; + + +/** + * Enumeration identifying the two ends of a pipe. + */ +enum GNUNET_DISK_PipeEnd + { + /** + * The reading-end of a pipe. + */ + GNUNET_DISK_PIPE_END_READ = 0, + + /** + * The writing-end of a pipe. + */ + GNUNET_DISK_PIPE_END_WRITE = 1 + }; + + /** * Get the number of blocks that are left on the partition that * contains the given file (for normal users). @@ -53,85 +222,229 @@ extern "C" long GNUNET_DISK_get_blocks_available (const char *part); +/** + * Checks whether a handle is invalid + * + * @param h handle to check + * @return GNUNET_YES if invalid, GNUNET_NO if valid + */ +int GNUNET_DISK_handle_invalid (const struct GNUNET_DISK_FileHandle *h); + + /** * Check that fil corresponds to a filename * (of a file that exists and that is not a directory). * - * @returns GNUNET_YES if yes, GNUNET_NO if not a file, GNUNET_SYSERR if something + * @param fil filename to check + * @return GNUNET_YES if yes, GNUNET_NO if not a file, GNUNET_SYSERR if something * else (will print an error message in that case, too). */ int GNUNET_DISK_file_test (const char *fil); +/** + * Move the read/write pointer in a file + * @param h handle of an open file + * @param offset position to move to + * @param whence specification to which position the offset parameter relates to + * @return the new position on success, GNUNET_SYSERR otherwise + */ +off_t +GNUNET_DISK_file_seek (const struct GNUNET_DISK_FileHandle *h, + off_t offset, + enum GNUNET_DISK_Seek whence); + + /** * Get the size of the file (or directory) * of the given file (in bytes). * + * @param filename name of the file or directory + * @param size set to the size of the file (or, + * in the case of directories, the sum + * of all sizes of files in the directory) * @param includeSymLinks should symbolic links be * included? - * * @return GNUNET_OK on success, GNUNET_SYSERR on error */ int GNUNET_DISK_file_size (const char *filename, - unsigned long long *size, int includeSymLinks); + uint64_t *size, + int includeSymLinks); /** - * Wrapper around "open()". Opens a file. + * Obtain some unique identifiers for the given file + * that can be used to identify it in the local system. + * This function is used between GNUnet processes to + * quickly check if two files with the same absolute path + * are actually identical. The two processes represent + * the same peer but may communicate over the network + * (and the file may be on an NFS volume). This function + * may not be supported on all operating systems. * - * @return file handle, -1 on error + * @param filename name of the file + * @param dev set to the device ID + * @param ino set to the inode ID + * @return GNUNET_OK on success */ -int GNUNET_DISK_file_open (const char *filename, int oflag, ...); +int GNUNET_DISK_file_get_identifiers (const char *filename, + uint64_t *dev, + uint64_t *ino); + +/** + * Create an (empty) temporary file on disk. If the given name is not + * an absolute path, the current 'TMPDIR' will be prepended. In any case, + * 6 random characters will be appended to the name to create a unique + * filename. + * + * @param t component to use for the name; + * does NOT contain "XXXXXX" or "/tmp/". + * @return NULL on error, otherwise name of fresh + * file on disk in directory for temporary files + */ +char * +GNUNET_DISK_mktemp (const char *t); + + +/** + * Open a file. Note that the access permissions will only be + * used if a new file is created and if the underlying operating + * system supports the given permissions. + * + * @param fn file name to be opened + * @param flags opening flags, a combination of GNUNET_DISK_OPEN_xxx bit flags + * @param perm permissions for the newly created file, use + * GNUNET_DISK_PERM_NONE if a file could not be created by this + * call (because of flags) + * @return IO handle on success, NULL on error + */ +struct GNUNET_DISK_FileHandle *GNUNET_DISK_file_open (const char *fn, + enum GNUNET_DISK_OpenFlags flags, + enum GNUNET_DISK_AccessPermissions perm); /** - * Wrapper around "close()". Closes a file. + * Creates an interprocess channel + * @param blocking creates an asynchronous pipe if set to GNUNET_NO + * @return handle to the new pipe, NULL on error */ -void GNUNET_DISK_file_close (const char *filename, int fd); +struct GNUNET_DISK_PipeHandle *GNUNET_DISK_pipe (int blocking); +/** + * Closes an interprocess channel + * @param p pipe + * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + */ +int GNUNET_DISK_pipe_close (struct GNUNET_DISK_PipeHandle *p); + +/** + * Closes one half of an interprocess channel + * + * @param p pipe to close end of + * @param end which end of the pipe to close + * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + */ +int +GNUNET_DISK_pipe_close_end (struct GNUNET_DISK_PipeHandle *p, + enum GNUNET_DISK_PipeEnd end); + +/** + * Close an open file. + * + * @param h file handle + * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + */ +int GNUNET_DISK_file_close (struct GNUNET_DISK_FileHandle *h); + + +/** + * Get the handle to a particular pipe end + * + * @param p pipe + * @param n end to access + * @return handle for the respective end + */ +const struct GNUNET_DISK_FileHandle * +GNUNET_DISK_pipe_handle (const struct + GNUNET_DISK_PipeHandle + *p, + enum GNUNET_DISK_PipeEnd n); + /** * Read the contents of a binary file into a buffer. - * @param fileName the name of the file, not freed, - * must already be expanded! + * @param h handle to an open file + * @param result the buffer to write the result to * @param len the maximum number of bytes to read + * @return the number of bytes read on success, GNUNET_SYSERR on failure + */ +ssize_t GNUNET_DISK_file_read (const struct GNUNET_DISK_FileHandle *h, void *result, + size_t len); + + +/** + * Read the contents of a binary file into a buffer. + * + * @param fn file name * @param result the buffer to write the result to - * @return the number of bytes read on success, -1 on failure + * @param len the maximum number of bytes to read + * @return number of bytes read, GNUNET_SYSERR on failure */ -int GNUNET_DISK_file_read (const char *fileName, int len, void *result); +ssize_t GNUNET_DISK_fn_read (const char *fn, + void *result, + size_t len); /** * Write a buffer to a file. - * @param fileName the name of the file, NOT freed! + * + * @param h handle to open file * @param buffer the data to write * @param n number of bytes to write - * @param mode the mode for file permissions - * @return GNUNET_OK on success, GNUNET_SYSERR on error + * @return number of bytes written on success, GNUNET_SYSERR on error + */ +ssize_t GNUNET_DISK_file_write (const struct GNUNET_DISK_FileHandle *h, + const void *buffer, + size_t n); + + +/** + * Write a buffer to a file. If the file is longer than + * the given buffer size, it will be truncated. + * + * @param fn file name + * @param buffer the data to write + * @param n number of bytes to write + * @param mode file permissions + * @return number of bytes written on success, GNUNET_SYSERR on error */ -int GNUNET_DISK_file_write (const char *fileName, - const void *buffer, unsigned int n, - const char *mode); +ssize_t GNUNET_DISK_fn_write (const char *fn, + const void *buffer, + size_t n, + enum GNUNET_DISK_AccessPermissions mode); /** * Copy a file. + * + * @param src file to copy + * @param dst destination file name * @return GNUNET_OK on success, GNUNET_SYSERR on error */ int GNUNET_DISK_file_copy (const char *src, const char *dst); /** - * Scan a directory for files. The name of the directory - * must be expanded first (!). + * Scan a directory for files. * * @param dirName the name of the directory * @param callback the method to call for each file - * @param data argument to pass to callback + * @param callback_cls closure for callback * @return the number of files found, -1 on error */ int GNUNET_DISK_directory_scan (const char *dirName, - GNUNET_FileNameCallback callback, void *data); + GNUNET_FileNameCallback callback, + void *callback_cls); /** @@ -145,7 +458,8 @@ struct GNUNET_DISK_DirectoryIterator; * * @param cls closure * @param di argument to pass to "GNUNET_DISK_directory_iterator_next" to - * get called on the next entry (or finish cleanly) + * get called on the next entry (or finish cleanly); + * NULL on error (will be the last call in that case) * @param filename complete filename (absolute path) * @param dirname directory name (absolute path) */ @@ -204,11 +518,12 @@ int GNUNET_DISK_directory_create_for_file (const char *filename); /** - * Test if fil is a directory that can be accessed. + * Test if "fil" is a directory that can be accessed. * Will not print an error message if the directory * does not exist. Will log errors if GNUNET_SYSERR is * returned. * + * @param fil filename to test * @return GNUNET_YES if yes, GNUNET_NO if does not exist, GNUNET_SYSERR * on any error and if exists but not directory */ @@ -234,6 +549,32 @@ int GNUNET_DISK_directory_remove (const char *fileName); int GNUNET_DISK_directory_create (const char *dir); +/** + * Lock a part of a file. + * + * @param fh file handle + * @param lockStart absolute position from where to lock + * @param lockEnd absolute position until where to lock + * @param excl GNUNET_YES for an exclusive lock + * @return GNUNET_OK on success, GNUNET_SYSERR on error + */ +int +GNUNET_DISK_file_lock (struct GNUNET_DISK_FileHandle *fh, off_t lockStart, + off_t lockEnd, int excl); + + +/** + * Unlock a part of a file + * @param fh file handle + * @param unlockStart absolute position from where to unlock + * @param unlockEnd absolute position until where to unlock + * @return GNUNET_OK on success, GNUNET_SYSERR on error + */ +int +GNUNET_DISK_file_unlock (struct GNUNET_DISK_FileHandle *fh, off_t unlockStart, + off_t unlockEnd); + + /** * @brief Removes special characters as ':' from a filename. * @param fn the filename to canonicalize @@ -257,15 +598,49 @@ int GNUNET_DISK_file_change_owner (const char *filename, const char *user); * a directory, end the last argument in '/' (or pass * DIR_SEPARATOR_STR as the last argument before NULL). * + * @param cfg configuration to use * @param serviceName name of the service asking - * @param varargs is NULL-terminated list of + * @param ... is NULL-terminated list of * path components to append to the * private directory name. * @return the constructed filename */ -char *GNUNET_DISK_get_home_filename (struct GNUNET_CONFIGURATION_Handle *cfg, +char *GNUNET_DISK_get_home_filename (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *serviceName, ...); + +/** + * Opaque handle for a memory-mapping operation. + */ +struct GNUNET_DISK_MapHandle; + +/** + * Map a file into memory + * @param h open file handle + * @param m handle to the new mapping (will be set) + * @param access access specification, GNUNET_DISK_MAP_TYPE_xxx + * @param len size of the mapping + * @return pointer to the mapped memory region, NULL on failure + */ +void *GNUNET_DISK_file_map (const struct GNUNET_DISK_FileHandle *h, + struct GNUNET_DISK_MapHandle **m, + enum GNUNET_DISK_MapType access, size_t len); + +/** + * Unmap a file + * + * @param h mapping handle + * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + */ +int GNUNET_DISK_file_unmap (struct GNUNET_DISK_MapHandle *h); + +/** + * Write file changes to disk + * @param h handle to an open file + * @return GNUNET_OK on success, GNUNET_SYSERR otherwise + */ +int GNUNET_DISK_file_sync (const struct GNUNET_DISK_FileHandle *h); + #if 0 /* keep Emacsens' auto-indent happy */ { #endif