* HOSTLIST:
- implement advertising of hostlist URL
- implement learning of hostlist URLs
+
* Remove KBlocks in gnunet-unindex (see discussion with Kenneth Almquist on gnunet-devs in 9/2009)
* Allow checking of presence of search results and/or content via command-line tools
(add options to gnunet-search / gnunet-download to limit search to local peer)
+* STATISTICS:
+ - should use BIO instead of mmap
len = (size_t) size;
data = GNUNET_DISK_file_map (h,
&map,
- GNUNET_DISK_MAP_READ,
+ GNUNET_DISK_MAP_TYPE_READ,
len);
GNUNET_assert (NULL != data);
GNUNET_FS_directory_list_contents (len,
*
* @param sock the service
* @param handler function to call with the message
- * @param cls closure for handler
+ * @param handler_cls closure for handler
* @param timeout how long to wait until timing out
*/
void GNUNET_CLIENT_receive (struct GNUNET_CLIENT_Connection *sock,
GNUNET_CLIENT_MessageHandler handler,
- void *cls, struct GNUNET_TIME_Relative timeout);
+ void *handler_cls,
+ struct GNUNET_TIME_Relative timeout);
/**
/*
This file is part of GNUnet.
- (C) 2006 Christian Grothoff (and other contributing authors)
+ (C) 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
/**
* Like snprintf, just aborts if the buffer is of insufficient size.
+ *
+ * @param buf pointer to buffer that is written to
+ * @param size number of bytes in buf
+ * @param format format strings
+ * @param ... data for format string
+ * @return number of bytes written to buf or negative value on error
*/
int GNUNET_snprintf (char *buf, size_t size, const char *format, ...);
+
/**
* Like asprintf, just portable.
+ *
+ * @param buf set to a buffer of sufficient size (allocated, caller must free)
+ * @param format format string (see printf, fprintf, etc.)
+ * @param ... data for format string
+ * @return number of bytes in "*buf" excluding 0-termination
*/
int GNUNET_asprintf (char **buf, const char *format, ...);
* memory is available. Don't use GNUNET_xmalloc_ directly. Use the
* GNUNET_malloc macro.
* The memory will be zero'ed out.
+ *
+ * @param size number of bytes to allocate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
*/
void *GNUNET_xmalloc_ (size_t size, const char *filename, int linenumber);
+
/**
* Allocate memory. This function does not check if the
* allocation request is within reasonable bounds, allowing
* allocations larger than 40 MB. If you don't expect the
* possibility of very large allocations, use GNUNET_malloc instead.
* The memory will be zero'ed out.
+ *
+ * @param size number of bytes to allocate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return allocated memory, never NULL
*/
void *GNUNET_xmalloc_unchecked_ (size_t size,
const char *filename, int linenumber);
* Free memory. Merely a wrapper for the case that we
* want to keep track of allocations. Don't use GNUNET_xfree_
* directly. Use the GNUNET_free macro.
+ *
+ * @param ptr pointer to memory to free
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
*/
void GNUNET_xfree_ (void *ptr, const char *filename, int linenumber);
/**
* Dup a string. Don't call GNUNET_xstrdup_ directly. Use the GNUNET_strdup macro.
+ * @param str string to duplicate
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
+ * @return the duplicated string
*/
char *GNUNET_xstrdup_ (const char *str, const char *filename, int linenumber);
* @param elementSize the size of the elements of the array
* @param oldCount address of the number of elements in the *old array
* @param newCount number of elements in the new array, may be 0 (then *old will be NULL afterwards)
+ * @param filename where is this call being made (for debugging)
+ * @param linenumber line where this call is being made (for debugging)
*/
void GNUNET_xgrow_ (void **old,
size_t elementSize,
EXTRACTOR_ExtractorList *
extractors);
+
+/**
+ * Options for metadata serialization.
+ */
enum GNUNET_CONTAINER_MetaDataSerializationOptions
{
+ /**
+ * Serialize all of the data.
+ */
GNUNET_CONTAINER_META_DATA_SERIALIZE_FULL = 0,
+
+ /**
+ * If not enough space is available, it is acceptable
+ * to only serialize some of the metadata.
+ */
GNUNET_CONTAINER_META_DATA_SERIALIZE_PART = 1,
+
+ /**
+ * Speed is of the essence, do not allow compression.
+ */
GNUNET_CONTAINER_META_DATA_SERIALIZE_NO_COMPRESS = 2
};
-
/**
* Serialize meta-data to target.
*
* Insert an element into a DLL. Assumes
* that head, tail and element are structs
* with prev and next fields.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param element element to insert
*/
#define GNUNET_CONTAINER_DLL_insert(head,tail,element) \
(element)->next = (head); \
* Insert an element into a DLL after the given other
* element. Insert at the head if the other
* element is NULL.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param other prior element, NULL for insertion at head of DLL
+ * @param element element to insert
*/
#define GNUNET_CONTAINER_DLL_insert_after(head,tail,other,element) \
(element)->prev = (other); \
* Remove an element from a DLL. Assumes
* that head, tail and element are structs
* with prev and next fields.
+ *
+ * @param head pointer to the head of the DLL
+ * @param tail pointer to the tail of the DLL
+ * @param element element to remove
*/
#define GNUNET_CONTAINER_DLL_remove(head,tail,element) \
if ((element)->prev == NULL) \
/**
* Inserts a new item into the heap, item is always neighbor now.
* @param heap the heap
+ * @param element element to insert
+ * @param cost cost of the element
+ * @return FIXME
*/
int
GNUNET_CONTAINER_heap_insert (struct GNUNET_CONTAINER_Heap *heap,
* Removes any node from the tree based on the neighbor given, does
* not traverse the tree (backpointers) but may take more time due to
* percolation of nodes.
+ *
* @param heap the heap
+ * @param element element to remove
+ * @return FIXME
*/
void *GNUNET_CONTAINER_heap_remove_node (struct GNUNET_CONTAINER_Heap *heap,
void *element);
* @param heap the heap
* @param element the element for which the cost is updated
* @param new_cost new cost for the element
- * @return WHAT?
+ * @return FIXME
*/
int
GNUNET_CONTAINER_heap_update_cost (struct GNUNET_CONTAINER_Heap *heap,
#include "gnunet_common.h"
#include "gnunet_scheduler_lib.h"
-
+/**
+ * Desired quality level for cryptographic operations.
+ */
enum GNUNET_CRYPTO_Quality
{
+ /**
+ * No good quality of the operation is needed (i.e.,
+ * random numbers can be pseudo-random).
+ */
GNUNET_CRYPTO_QUALITY_WEAK,
+
+ /**
+ * High-quality operations are desired.
+ */
GNUNET_CRYPTO_QUALITY_STRONG
};
/**
* Create a new Session key.
+ *
+ * @param key key to initialize
*/
void GNUNET_CRYPTO_aes_create_session_key (struct GNUNET_CRYPTO_AesSessionKey
*key);
/**
* Check that a new session key is well-formed.
*
+ * @param key key to check
* @return GNUNET_OK if the key is valid
*/
int GNUNET_CRYPTO_aes_check_session_key (const struct
* a.a or a.e (they're used elsewhere), and
* be somewhat consistent. And of course, the
* result should be a positive number.
+ *
+ * @param a some hash code
+ * @param b some hash code
* @return number between 0 and 65536
*/
uint32_t GNUNET_CRYPTO_hash_distance_u32 (const GNUNET_HashCode * a,
/**
* Create a random hash code.
+ *
+ * @param mode desired quality level
+ * @param result hash code that is randomized
*/
void GNUNET_CRYPTO_hash_create_random (enum GNUNET_CRYPTO_Quality mode,
GNUNET_HashCode * result);
/**
* compute result(delta) = b - a
+ *
+ * @param a some hash code
+ * @param b some hash code
+ * @param result set to b - a
*/
void GNUNET_CRYPTO_hash_difference (const GNUNET_HashCode * a,
const GNUNET_HashCode * b,
/**
* compute result(b) = a + delta
+ *
+ * @param a some hash code
+ * @param delta some hash code
+ * @param result set to a + delta
*/
void GNUNET_CRYPTO_hash_sum (const GNUNET_HashCode * a,
const GNUNET_HashCode * delta,
/**
* compute result = a ^ b
+ *
+ * @param a some hash code
+ * @param b some hash code
+ * @param result set to a ^ b
*/
void GNUNET_CRYPTO_hash_xor (const GNUNET_HashCode * a,
const GNUNET_HashCode * b,
/**
* Convert a hashcode into a key.
+ *
+ * @param hc hash code that serves to generate the key
+ * @param skey set to a valid session key
+ * @param iv set to a valid initialization vector
*/
void GNUNET_CRYPTO_hash_to_aes_key (const GNUNET_HashCode * hc,
struct GNUNET_CRYPTO_AesSessionKey *skey,
/**
* Obtain a bit from a hashcode.
+ *
* @param code the GNUNET_CRYPTO_hash to index bit-wise
* @param bit index into the hashcode, [0...159]
* @return Bit \a bit from hashcode \a code, -1 for invalid index
/**
* Compare function for HashCodes, producing a total ordering
* of all hashcodes.
+ *
+ * @param h1 some hash code
+ * @param h2 some hash code
* @return 1 if h1 > h2, -1 if h1 < h2 and 0 if h1 == h2.
*/
int GNUNET_CRYPTO_hash_cmp (const GNUNET_HashCode * h1,
/**
* Find out which of the two GNUNET_CRYPTO_hash codes is closer to target
* in the XOR metric (Kademlia).
+ *
+ * @param h1 some hash code
+ * @param h2 some hash code
+ * @param target some hash code
* @return -1 if h1 is closer, 1 if h2 is closer and 0 if h1==h2.
*/
int GNUNET_CRYPTO_hash_xorcmp (const GNUNET_HashCode * h1,
/**
* Create a new private key. Caller must free return value.
+ *
+ * @return fresh private key
*/
struct GNUNET_CRYPTO_RsaPrivateKey *GNUNET_CRYPTO_rsa_key_create (void);
* are invalid the old file is deleted and a fresh key is
* created.
*
+ * @param filename name of file to use for storage
* @return new private key, NULL on error (for example,
* permission denied)
*/
/**
* Deterministically (!) create a private key using only the
* given HashCode as input to the PRNG.
+ *
+ * @param input "random" input to PRNG
+ * @return some private key purely dependent on input
*/
struct GNUNET_CRYPTO_RsaPrivateKey
*GNUNET_CRYPTO_rsa_key_create_from_hash (const GNUNET_HashCode * input);
/**
* Extract the public key of the host.
- * @param result where to write the result.
+ *
+ * @param priv the private key
+ * @param pub where to write the public key
*/
void GNUNET_CRYPTO_rsa_key_get_public (const struct
- GNUNET_CRYPTO_RsaPrivateKey *hostkey,
+ GNUNET_CRYPTO_RsaPrivateKey *priv,
struct
GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded
- *result);
+ *pub);
/**
/**
* This function should only be called in testcases
* where strong entropy gathering is not desired
- * (for example, for hostkey generation).
+ * (for example, for hostkey generation).
*/
void GNUNET_CRYPTO_random_disable_entropy_gathering (void);
#endif
#endif
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_ANY 0
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_DBLOCK 1
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_IBLOCK 2
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_KBLOCK 3
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_SBLOCK 4
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_ONDEMAND 5
+
+/**
+ * FIXME.
+ */
#define GNUNET_DATASTORE_BLOCKTYPE_SKBLOCK 6 /* not yet used */
+
/**
* Handle to the datastore service.
*/
#endif
-/* Open the file for reading */
-#define GNUNET_DISK_OPEN_READ 1
-/* Open the file for writing */
-#define GNUNET_DISK_OPEN_WRITE 2
-/* Open the file for both reading and writing */
-#define GNUNET_DISK_OPEN_READWRITE 3
-/* Fail if file already exists */
-#define GNUNET_DISK_OPEN_FAILIFEXISTS 4
-/* Truncate file if it exists */
-#define GNUNET_DISK_OPEN_TRUNCATE 8
-/* Create file if it doesn't exist */
-#define GNUNET_DISK_OPEN_CREATE 16
-/* Append to the file */
-#define GNUNET_DISK_OPEN_APPEND 32
-
-#define GNUNET_DISK_MAP_READ 1
-#define GNUNET_DISK_MAP_WRITE 2
-#define GNUNET_DISK_MAP_READWRITE 3
+/**
+ * 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
+ };
+
+
+// FIXME: use enum here!
#define GNUNET_DISK_PERM_USER_READ 1
#define GNUNET_DISK_PERM_USER_WRITE 2
#define GNUNET_DISK_PERM_USER_EXEC 4
#define GNUNET_DISK_PERM_OTHER_WRITE 128
#define 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
};
* 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);
/**
- * FIXME.
+ * 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.
*
* @param filename name of the file
* @param dev set to the device ID
* file on disk in directory for temporary files
*/
char *
-GNUNET_DISK_mktemp (const char *t);
+GNUNET_DISK_mktemp (const char *template);
/**
- * Open a file
+ * Open a file.
+ *
* @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
+ * @param ... permissions for the newly created file (only required if creation is possible)
* @return IO handle on success, NULL on error
*/
-struct GNUNET_DISK_FileHandle *GNUNET_DISK_file_open (const char *fn, int flags, ...);
+struct GNUNET_DISK_FileHandle *GNUNET_DISK_file_open (const char *fn,
+ enum GNUNET_DISK_OpenFlags flags,
+ ...);
/**
* Creates an interprocess channel
/**
* Get the handle to a particular pipe end
* @param p pipe
- * @param n number of the end
+ * @param n number of the end (0 or 1); FIXME: use enum here!
+ * @return handle for the respective end
*/
const struct GNUNET_DISK_FileHandle *GNUNET_DISK_pipe_handle (const struct
GNUNET_DISK_PipeHandle
* 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
*/
/**
- * Lock a part of a file
+ * Lock a part of a file.
+ *
* @param fh file handle
- * @lockStart absolute position from where to lock
- * @lockEnd absolute position until where to lock
- * @excl GNUNET_YES for an exclusive lock
+ * @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
- * @lockStart absolute position from where to unlock
- * @lockEnd absolute position until where to unlock
+ * @param lockStart absolute position from where to unlock
+ * @param lockEnd absolute position until where to unlock
* @return GNUNET_OK on success, GNUNET_SYSERR on error
*/
int
* 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
* path components to append to the
* 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_xxx
+ * @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,
- int access, size_t len);
+ enum GNUNET_DISK_MapType access, size_t len);
/**
* Unmap a file
const struct GNUNET_GETOPT_CommandLineOption
*allOptions, unsigned int argc, char *const *argv);
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_set_ulong (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
const char *value);
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_set_uint (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
const char *value);
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_set_one (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
const char *value);
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_set_string (struct GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
const char *value);
+/**
+ * FIXME
+ */
int
GNUNET_GETOPT_increment_value (struct
GNUNET_GETOPT_CommandLineProcessorContext *ctx,
/* *************** internal prototypes - use macros above! ************* */
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_format_help_ (struct
GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
const char *value);
+/**
+ * FIXME
+ */
int GNUNET_GETOPT_print_version_ (struct
GNUNET_GETOPT_CommandLineProcessorContext
*ctx, void *scls, const char *option,
socklen_t *address_len);
/**
- * Make a non-inheritable to child processes
+ * Make a non-inheritable to child processes (sets the
+ * close-on-exec flag).
+ *
* @param socket
* @return GNUNET_OK on success, GNUNET_SYSERR otherwise
* @warning Not implemented on Windows
/**
* Read data from a connected socket
+ *
* @param desc socket
* @param buffer buffer
* @param length length of buffer
* @param flags type of message reception
+ * @return number of bytes read
*/
ssize_t GNUNET_NETWORK_socket_recv (const struct GNUNET_NETWORK_Handle *desc, void *buffer,
size_t length, int flags);
* @param doBlock blocking mode
* @return GNUNET_OK on success, GNUNET_SYSERR on error
*/
-int GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd, int doBlock);
+int GNUNET_NETWORK_socket_set_blocking (struct GNUNET_NETWORK_Handle *fd,
+ int doBlock);
/**
* Send data
struct GNUNET_NETWORK_Handle *GNUNET_NETWORK_socket_socket (int domain, int type, int protocol);
/**
- * Reset FD set
- * @param fds fd set
+ * Reset FD set (clears all file descriptors).
+ *
+ * @param fds fd set to clear
*/
void GNUNET_NETWORK_fdset_zero(struct GNUNET_NETWORK_FDSet *fds);
* @param desc socket to add
*/
void GNUNET_NETWORK_fdset_set(struct GNUNET_NETWORK_FDSet *fds,
- const struct GNUNET_NETWORK_Handle *desc);
+ const struct GNUNET_NETWORK_Handle *desc);
+
/**
* Check whether a socket is part of the fd set
* @param desc socket
*/
int GNUNET_NETWORK_fdset_isset(const struct GNUNET_NETWORK_FDSet *fds,
- const struct GNUNET_NETWORK_Handle *desc);
+ const struct GNUNET_NETWORK_Handle *desc);
/**
* Add one fd set to another
* @param src the fd set to add from
*/
void GNUNET_NETWORK_fdset_add (struct GNUNET_NETWORK_FDSet *dst,
- const struct GNUNET_NETWORK_FDSet *src);
+ const struct GNUNET_NETWORK_FDSet *src);
/**
* Copy one fd set to another
* @param from source
*/
void GNUNET_NETWORK_fdset_copy(struct GNUNET_NETWORK_FDSet *to,
- const struct GNUNET_NETWORK_FDSet *from);
+ const struct GNUNET_NETWORK_FDSet *from);
/**
* Copy a native fd set
* @param from native source set
* @param the biggest socket number in from + 1
*/
-void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to, const fd_set *from,
- int nfds);
+void GNUNET_NETWORK_fdset_copy_native (struct GNUNET_NETWORK_FDSet *to,
+ const fd_set *from,
+ int nfds);
/**
* Add a file handle to the fd set
* @param h the file handle to add
*/
void GNUNET_NETWORK_fdset_handle_set (struct GNUNET_NETWORK_FDSet *fds,
- const struct GNUNET_DISK_FileHandle *h);
+ const struct GNUNET_DISK_FileHandle *h);
/**
* Check if a file handle is part of an fd set
* @return GNUNET_YES if the file handle is part of the set
*/
int GNUNET_NETWORK_fdset_handle_isset (const struct GNUNET_NETWORK_FDSet *fds,
- const struct GNUNET_DISK_FileHandle *h);
+ const struct GNUNET_DISK_FileHandle *h);
/**
* Checks if two fd sets overlap
* @param fds2 second fd set
* @return GNUNET_YES if they do overlap, GNUNET_NO otherwise
*/
-int GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1, const struct GNUNET_NETWORK_FDSet *fds2);
+int GNUNET_NETWORK_fdset_overlap (const struct GNUNET_NETWORK_FDSet *fds1,
+ const struct GNUNET_NETWORK_FDSet *fds2);
/**
* Creates an fd set
*/
enum GNUNET_OS_InstallationPathKind
{
+ /**
+ * Return the "PREFIX" directory given to configure.
+ */
GNUNET_OS_IPK_PREFIX,
+
+ /**
+ * Return the directory where the program binaries are installed. (bin/)
+ */
GNUNET_OS_IPK_BINDIR,
+
+ /**
+ * Return the directory where libraries are installed. (lib/)
+ */
GNUNET_OS_IPK_LIBDIR,
+
+ /**
+ * Return the directory where data is installed (share/)
+ */
GNUNET_OS_IPK_DATADIR,
+
+ /**
+ * Return the directory where translations are installed (share/locale/)
+ */
GNUNET_OS_IPK_LOCALEDIR,
+
+ /**
+ * Return the installation directory of this application, not
+ * the one of the overall GNUnet installation (in case they
+ * are different).
+ */
GNUNET_OS_IPK_SELF_PREFIX
};
*/
enum GNUNET_OS_ProcessStatusType
{
+ /**
+ * The process is not known to the OS (or at
+ * least not one of our children).
+ */
GNUNET_OS_PROCESS_UNKNOWN,
+
+ /**
+ * The process is still running.
+ */
GNUNET_OS_PROCESS_RUNNING,
+
+ /**
+ * The process is paused (but could be resumed).
+ */
GNUNET_OS_PROCESS_STOPPED,
+
+ /**
+ * The process exited with a return code.
+ */
GNUNET_OS_PROCESS_EXITED,
+
+ /**
+ * The process was killed by a signal.
+ */
GNUNET_OS_PROCESS_SIGNALED
};
/**
* @brief Enumerate all network interfaces
- * @param callback the callback function
+ * @param proc the callback function
+ * @param proc_cls closure for proc
*/
void GNUNET_OS_network_interfaces_list (GNUNET_OS_NetworkInterfaceProcessor
- proc, void *cls);
+ proc, void *proc_cls);
/**
* Get the current CPU load.
/**
* Signature of any function exported by a plugin.
+ *
+ * @param arg argument to the function (context)
+ * @return some pointer, NULL if the plugin was
+ * shutdown or if there was an error, otherwise
+ * the plugin's API on success
*/
typedef void *(*GNUNET_PLUGIN_Callback) (void *arg);
*
* @param library_name name of the plugin to load
* @param arg argument to the plugin initialization function
- * @return whatever the initialization function returned
+ * @return whatever the initialization function returned, NULL on error
*/
void *GNUNET_PLUGIN_load (const char *library_name, void *arg);
*
* @param library_name name of the plugin to unload
* @param arg argument to the plugin shutdown function
- * @return whatever the shutdown function returned
+ * @return whatever the shutdown function returned, typically NULL
+ * or a "char *" representing the error message
*/
void *GNUNET_PLUGIN_unload (const char *library_name, void *arg);
#endif
#endif
+/**
+ * Context created when a signal handler is installed;
+ * can be used to restore it to the previous state later.
+ */
struct GNUNET_SIGNAL_Context;
/**
/**
* Install a signal handler that will be run if the
* given signal is received.
+ *
+ * @param signal the number of the signal
+ * @param handler the function to call
+ * @return context that can be used to restore, NULL on error
*/
struct GNUNET_SIGNAL_Context *GNUNET_SIGNAL_handler_install (int signal,
GNUNET_SIGNAL_Handler
/**
* Uninstall a previously installed signal hander.
+ *
+ * @param ctx context that was returned when the
+ * signal handler was installed
*/
void GNUNET_SIGNAL_handler_uninstall (struct GNUNET_SIGNAL_Context *ctx);
/**
* Convert a given filesize into a fancy human-readable format.
+ *
+ * @param size number of bytes
+ * @return fancy representation of the size (possibly rounded) for humans
*/
char *GNUNET_STRINGS_byte_size_fancy (unsigned long long size);
+
/**
* Convert the len characters long character sequence
* given in input that is in the given charset
* to UTF-8.
*
+ * @param input the input string (not necessarily 0-terminated)
+ * @param len the number of bytes in the input
+ * @param charset character set to convert from
* @return the converted string (0-terminated)
*/
char *GNUNET_STRINGS_to_utf8 (const char *input,
size_t len, const char *charset);
+
/**
* Complete filename (a la shell) from abbrevition.
*
* @param fil the name of the file, may contain ~/ or
* be relative to the current directory
- * @returns the full file name,
+ * @return the full file name,
* NULL is returned on error
*/
char *GNUNET_STRINGS_filename_expand (const char *fil);
* used to parse the buffer back into individual
* strings.
*
+ * @param buffer the buffer to fill with strings, can
+ * be NULL in which case only the necessary
+ * amount of space will be calculated
+ * @param size number of bytes available in buffer
+ * @param count number of strings that follow
+ * @param ... count 0-terminated strings to copy to buffer
* @return number of bytes written to the buffer
* (or number of bytes that would have been written)
*/
-unsigned int GNUNET_STRINGS_buffer_fill (char *buffer,
- unsigned int size,
- unsigned int count, ...);
+size_t GNUNET_STRINGS_buffer_fill (char *buffer,
+ size_t size,
+ unsigned int count, ...);
+
/**
* Given a buffer of a given size, find "count"
* @param buffer the buffer to parse
* @param size size of the buffer
* @param count number of strings to locate
+ * @param ... pointers to where to store the strings
* @return offset of the character after the last 0-termination
* in the buffer, or 0 on error.
*/
unsigned int GNUNET_STRINGS_buffer_tokenize (const char *buffer,
- unsigned int size,
+ size_t size,
unsigned int count, ...);
*/
char *GNUNET_STRINGS_relative_time_to_string (struct GNUNET_TIME_Relative
delta);
+
#if 0 /* keep Emacsens' auto-indent happy */
{
#endif
*/
struct GNUNET_TIME_Absolute
{
+ /**
+ * The actual value.
+ */
uint64_t value;
};
*/
struct GNUNET_TIME_Relative
{
+ /**
+ * The actual value.
+ */
uint64_t value;
};
*/
struct GNUNET_TIME_RelativeNBO
{
+ /**
+ * The actual value (in network byte order).
+ */
uint64_t value__ GNUNET_PACKED;
};
*/
struct GNUNET_TIME_AbsoluteNBO
{
+ /**
+ * The actual value (in network byte order).
+ */
uint64_t value__ GNUNET_PACKED;
};
/**
- * @brief constants to specify time
+ * Relative time zero.
*/
#define GNUNET_TIME_UNIT_ZERO GNUNET_TIME_relative_get_zero()
+
+/**
+ * Absolute time zero.
+ */
#define GNUNET_TIME_UNIT_ZERO_ABS GNUNET_TIME_absolute_get_zero()
+
+/**
+ * One millisecond, our basic time unit.
+ */
#define GNUNET_TIME_UNIT_MILLISECONDS GNUNET_TIME_relative_get_unit()
+
+/**
+ * One second.
+ */
#define GNUNET_TIME_UNIT_SECONDS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MILLISECONDS, 1000)
+
+/**
+ * One minute.
+ */
#define GNUNET_TIME_UNIT_MINUTES GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_SECONDS, 60)
+
+/**
+ * One hour.
+ */
#define GNUNET_TIME_UNIT_HOURS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MINUTES, 60)
+
+/**
+ * One day.
+ */
#define GNUNET_TIME_UNIT_DAYS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_HOURS, 24)
+
+/**
+ * One week.
+ */
#define GNUNET_TIME_UNIT_WEEKS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS, 7)
+
+/**
+ * One month (30 days).
+ */
#define GNUNET_TIME_UNIT_MONTHS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS, 30)
+
+/**
+ * One year (365 days).
+ */
#define GNUNET_TIME_UNIT_YEARS GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_DAYS, 365)
/**
* Convert relative time to an absolute time in the
* future.
*
+ * @param rel relative time to convert
* @return timestamp that is "rel" in the future, or FOREVER if rel==FOREVER (or if we would overflow)
*/
struct GNUNET_TIME_Absolute GNUNET_TIME_relative_to_absolute (struct
/**
* Return the minimum of two relative time values.
*
+ * @param t1 first timestamp
+ * @param t2 other timestamp
* @return timestamp that is smaller
*/
struct GNUNET_TIME_Relative GNUNET_TIME_relative_min (struct
* Given a timestamp in the future, how much time
* remains until then?
*
+ * @param future some absolute time, typically in the future
* @return future - now, or 0 if now >= future, or FOREVER if future==FOREVER.
*/
struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_remaining (struct
* Use this function instead of actual subtraction to ensure that
* "FOREVER" and overflows are handeled correctly.
*
+ * @param start some absolute time
+ * @param end some absolute time (typically larger or equal to start)
* @return 0 if start >= end; FOREVER if end==FOREVER; otherwise end - start
*/
struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_difference (struct
* Get the duration of an operation as the
* difference of the current time and the given start time "hence".
*
+ * @param hence some absolute time, typically in the past
* @return aborts if hence==FOREVER, 0 if hence > now, otherwise now-hence.
*/
struct GNUNET_TIME_Relative GNUNET_TIME_absolute_get_duration (struct
* Add a given relative duration to the
* given start time.
*
+ * @param start some absolute time
+ * @param duration some relative time to add
* @return FOREVER if either argument is FOREVER or on overflow; start+duration otherwise
*/
struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_add (struct
/**
* Multiply relative time by a given factor.
*
+ * @param rel some duration
+ * @param factor integer to multiply with
* @return FOREVER if rel=FOREVER or on overflow; otherwise rel*factor
*/
struct GNUNET_TIME_Relative GNUNET_TIME_relative_multiply (struct
/**
* Add relative times together.
*
+ * @param a1 some relative time
+ * @param a2 some other relative time
* @return FOREVER if either argument is FOREVER or on overflow; a1+a2 otherwise
*/
struct GNUNET_TIME_Relative GNUNET_TIME_relative_add (struct
/**
* Convert relative time to network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
*/
struct GNUNET_TIME_RelativeNBO GNUNET_TIME_relative_hton (struct
GNUNET_TIME_Relative
/**
* Convert relative time from network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
*/
struct GNUNET_TIME_Relative GNUNET_TIME_relative_ntoh (struct
GNUNET_TIME_RelativeNBO
/**
* Convert relative time to network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
*/
struct GNUNET_TIME_AbsoluteNBO GNUNET_TIME_absolute_hton (struct
GNUNET_TIME_Absolute
/**
* Convert relative time from network byte order.
+ *
+ * @param a time to convert
+ * @return converted time value
*/
struct GNUNET_TIME_Absolute GNUNET_TIME_absolute_ntoh (struct
GNUNET_TIME_AbsoluteNBO
* @file statistics/gnunet-service-statistics.c
* @brief program that tracks statistics
* @author Christian Grothoff
+ *
+ * TODO:
+ * - use BIO for IO operations
*/
#include "platform.h"
#include "gnunet_disk_lib.h"
GNUNET_free (fn);
return;
}
- buf = GNUNET_DISK_file_map (fh, &mh, GNUNET_DISK_MAP_READ, sb.st_size);
+ buf = GNUNET_DISK_file_map (fh, &mh, GNUNET_DISK_MAP_TYPE_READ, sb.st_size);
if (NULL == buf)
{
GNUNET_log_strerror_file (GNUNET_ERROR_TYPE_WARNING, "mmap", fn);
}
+/**
+ * Like asprintf, just portable.
+ *
+ * @param buf set to a buffer of sufficient size (allocated, caller must free)
+ * @param format format string (see printf, fprintf, etc.)
+ * @param ... data for format string
+ * @return number of bytes in "*buf" excluding 0-termination
+ */
int
GNUNET_asprintf (char **buf, const char *format, ...)
{
return ret;
}
+
+/**
+ * Like snprintf, just aborts if the buffer is of insufficient size.
+ *
+ * @param buf pointer to buffer that is written to
+ * @param size number of bytes in buf
+ * @param format format strings
+ * @param ... data for format string
+ * @return number of bytes written to buf or negative value on error
+ */
int
GNUNET_snprintf (char *buf, size_t size, const char *format, ...)
{
/**
* Lock a part of a file
* @param fh file handle
- * @lockStart absolute position from where to lock
- * @lockEnd absolute position until where to lock
- * @excl GNUNET_YES for an exclusive lock
+ * @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
/**
* Unlock a part of a file
* @param fh file handle
- * @lockStart absolute position from where to unlock
- * @lockEnd absolute position until where to unlock
+ * @param lockStart absolute position from where to unlock
+ * @param lockEnd absolute position until where to unlock
* @return GNUNET_OK on success, GNUNET_SYSERR on error
*/
int
* Open a file
* @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
+ * @param ... permissions for the newly created file
* @return IO handle on success, NULL on error
*/
struct GNUNET_DISK_FileHandle *
-GNUNET_DISK_file_open (const char *fn, int flags, ...)
+GNUNET_DISK_file_open (const char *fn,
+ enum GNUNET_DISK_OpenFlags flags,
+ ...)
{
char *expfn;
struct GNUNET_DISK_FileHandle *ret;
* Map a file into memory
* @param h open file handle
* @param m handle to the new mapping
- * @param access access specification, GNUNET_DISK_MAP_xxx
+ * @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,
- int access, size_t len)
+ enum GNUNET_DISK_MapType access, size_t len)
{
if (h == NULL)
{
DWORD mapAccess, protect;
void *ret;
- if (access & GNUNET_DISK_MAP_READ && access & GNUNET_DISK_MAP_WRITE)
+ if ((access & GNUNET_DISK_MAP_TYPE_READ) &&
+ (access & GNUNET_DISK_MAP_TYPE_WRITE))
{
protect = PAGE_READWRITE;
mapAccess = FILE_MAP_ALL_ACCESS;
}
- else if (access & GNUNET_DISK_MAP_READ)
+ else if (access & GNUNET_DISK_MAP_TYPE_READ)
{
protect = PAGE_READONLY;
mapAccess = FILE_MAP_READ;
}
- else if (access & GNUNET_DISK_MAP_WRITE)
+ else if (access & GNUNET_DISK_MAP_TYPE_WRITE)
{
protect = PAGE_READWRITE;
mapAccess = FILE_MAP_WRITE;
int prot;
prot = 0;
- if (access & GNUNET_DISK_MAP_READ)
+ if (access & GNUNET_DISK_MAP_TYPE_READ)
prot = PROT_READ;
- if (access & GNUNET_DISK_MAP_WRITE)
+ if (access & GNUNET_DISK_MAP_TYPE_WRITE)
prot |= PROT_WRITE;
*m = GNUNET_malloc (sizeof (struct GNUNET_DISK_MapHandle));
(*m)->addr = mmap (NULL, len, prot, MAP_SHARED, h->fd, 0);
* used to parse the buffer back into individual
* strings.
*
+ * @param buffer the buffer to fill with strings, can
+ * be NULL in which case only the necessary
+ * amount of space will be calculated
+ * @param size number of bytes available in buffer
+ * @param count number of strings that follow
+ * @param ... count 0-terminated strings to copy to buffer
* @return number of bytes written to the buffer
* (or number of bytes that would have been written)
*/
unsigned int
GNUNET_STRINGS_buffer_fill (char *buffer,
- unsigned int size, unsigned int count, ...)
+ size_t size, unsigned int count, ...)
{
unsigned int needed;
unsigned int slen;
*/
unsigned int
GNUNET_STRINGS_buffer_tokenize (const char *buffer,
- unsigned int size, unsigned int count, ...)
+ size_t size, unsigned int count, ...)
{
unsigned int start;
unsigned int needed;
/**
* Convert a given filesize into a fancy human-readable format.
+ *
+ * @param size number of bytes
+ * @return fancy representation of the size (possibly rounded) for humans
*/
char *
GNUNET_STRINGS_byte_size_fancy (unsigned long long size)
projects / oweals / gnunet.git / commitdiff