957 lines
39 KiB
Plaintext
957 lines
39 KiB
Plaintext
This is libcfu.info, produced by makeinfo version 4.7 from libcfu.texi.
|
||
|
||
Copyright (C) 2005 Don Owens
|
||
|
||
This code is released under the BSD license:
|
||
|
||
Redistribution and use in source and binary forms, with or without
|
||
modification, are permitted provided that the following conditions are
|
||
met:
|
||
|
||
* Redistributions of source code must retain the above copyright
|
||
notice, this list of conditions and the following disclaimer.
|
||
|
||
* Redistributions in binary form must reproduce the above
|
||
copyright notice, this list of conditions and the following
|
||
disclaimer in the documentation and/or other materials provided with
|
||
the distribution.
|
||
|
||
* Neither the name of the author nor the names of its
|
||
contributors may be used to endorse or promote products derived from
|
||
this software without specific prior written permission.
|
||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
||
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
||
INFO-DIR-SECTION Libraries
|
||
START-INFO-DIR-ENTRY
|
||
* Libcfu: (libcfu). The cfu library.
|
||
END-INFO-DIR-ENTRY
|
||
|
||
This manual describes the external interface to libcfu version
|
||
0.03
|
||
|
||
Copyright (C) 2005 Don Owens All rights reserved.
|
||
|
||
This code is released under the BSD license:
|
||
|
||
Redistribution and use in source and binary forms, with or without
|
||
modification, are permitted provided that the following conditions are
|
||
met:
|
||
|
||
* Redistributions of source code must retain the above copyright
|
||
notice, this list of conditions and the following disclaimer.
|
||
|
||
* Redistributions in binary form must reproduce the above
|
||
copyright notice, this list of conditions and the following
|
||
disclaimer in the documentation and/or other materials provided with
|
||
the distribution.
|
||
|
||
* Neither the name of the author nor the names of its
|
||
contributors may be used to endorse or promote products derived from
|
||
this software without specific prior written permission.
|
||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
||
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
||
|
||
File: libcfu.info, Node: Top, Next: Data structures, Prev: (dir), Up: (dir)
|
||
|
||
This manual describes the interface to libcfu version 0.03
|
||
|
||
Copyright (C) 2005 Don Owens
|
||
|
||
* Menu:
|
||
|
||
* Data structures::
|
||
* Conf:: For reading configuration files
|
||
* Options:: For parsing command-line arguments
|
||
* Thread queue:: For queueing up requests for a separate thread
|
||
* Timer:: An easy to use timer
|
||
|
||
* License:: License under which libcfu is distributed
|
||
|
||
* Concept index::
|
||
* Function index::
|
||
|
||
|
||
File: libcfu.info, Node: Data structures, Prev: Top, Up: Top
|
||
|
||
1 Data structures
|
||
*****************
|
||
|
||
* Menu:
|
||
|
||
* Hash table:: For key/value pairs
|
||
* Linked list:: For unordered data
|
||
* Strings:: For self-extending strings
|
||
|
||
|
||
File: libcfu.info, Node: Hash table, Next: Linked list, Prev: Data structures, Up: Data structures
|
||
|
||
1.1 Hash table
|
||
==============
|
||
|
||
-- Special Form: typedef u_int32_t (*cfuhash_function_t)(const void *
|
||
KEY, size_t LENGTH)
|
||
Prototype for a pointer to a hashing function.
|
||
|
||
-- Special Form: typedef void (*cfuhash_free_fn_t)(void * DATA)
|
||
Prototype for a pointer to a free function.
|
||
|
||
-- Special Form: typedef int (*cfuhash_remove_fn_t)(void * KEY, size_t
|
||
KEY_SIZE, void * DATA, size_t DATA_SIZE, void * ARG)
|
||
Prototype for a pointer to a function that determines whether or
|
||
not to remove an entry from the hash.
|
||
|
||
-- Special Form: typedef int (*cfuhash_foreach_fn_t)(void * KEY,
|
||
size_t KEY_SIZE, void * DATA, size_t DATA_SIZE, void * ARG)
|
||
Prototype for a pointer to a function to be called foreach
|
||
key/value pair in the hash by cfuhash_foreach(). The return
|
||
value should normally be zero. A non-zero return value means to
|
||
stop iterating over the key/value pairs.
|
||
|
||
-- Function: cfuhash_table_t * cfuhash_new (size_t SIZE, u_int32_t
|
||
FLAGS)
|
||
Creates a new hash table.
|
||
|
||
-- Function: cfuhash_table_t * cfuhash_new_with_initial_size (size_t
|
||
SIZE)
|
||
Creates a new hash table with the specified size (number of
|
||
buckets).
|
||
|
||
|
||
-- Function: cfuhash_table_t * cfuhash_new_with_flags (u_int32_t FLAGS)
|
||
Creates a new hash table with the specified flags. Pass zero for
|
||
flags if you want the defaults.
|
||
|
||
-- Function: cfuhash_table_t * cfuhash_new_with_free_fn (size_t SIZE,
|
||
u_int32_t FLAGS, cfuhash_free_fn_t FF)
|
||
Same as cfuhash_new() except automatically calls
|
||
cfuhash_set_free_fn().
|
||
|
||
-- Function: int cfuhash_copy (cfuhash_table_t * SRC, cfuhash_table_t
|
||
* DST)
|
||
Copies entries in src to dst
|
||
|
||
-- Function: cfuhash_table_t * cfuhash_merge (cfuhash_table_t * HT1,
|
||
cfuhash_table_t * HT2, u_int32_t FLAGS)
|
||
Returns a new hash containing entries from both hash tables. For
|
||
any entries with the same key, the one from ht2 wins.
|
||
|
||
|
||
-- Function: int cfuhash_set_hash_function (cfuhash_table_t * HT,
|
||
cfuhash_function_t HF)
|
||
Sets the hashing function to use when computing which bucket to add
|
||
entries to. It should return a 32-bit unsigned integer. By
|
||
default, Perl's hashing algorithm is used.
|
||
|
||
|
||
-- Function: int cfuhash_set_thresholds (cfuhash_table_t * HT, float
|
||
LOW, float HIGH)
|
||
Sets the thresholds for when to rehash. The ratio
|
||
num_entries/buckets is compared against low and high. If it is
|
||
below 'low' or above 'high', the hash will shrink or grow,
|
||
respectively, unless the flags say to do otherwise.
|
||
|
||
|
||
-- Function: int cfuhash_set_free_function (cfuhash_table_t * HT,
|
||
cfuhash_free_fn_t FF)
|
||
Sets the function to use when removing an entry from the hash,
|
||
i.e., when replacing an existing entry, deleting an entry, or
|
||
clearing the hash. It is passed the value of the entry as a void
|
||
*.
|
||
|
||
|
||
-- Function: u_int32_t cfuhash_get_flags (cfuhash_table_t * HT)
|
||
Returns the hash's flags. See below for flag definitions.
|
||
|
||
-- Function: u_int32_t cfuhash_set_flag (cfuhash_table_t * HT,
|
||
u_int32_t FLAG)
|
||
Sets a flag.
|
||
|
||
-- Function: u_int32_t cfuhash_clear_flag (cfuhash_table_t * HT,
|
||
u_int32_t NEW_FLAG)
|
||
Clears a flag.
|
||
|
||
-- Function: int cfuhash_get_data (cfuhash_table_t * HT, const void *
|
||
KEY, size_t KEY_SIZE, void ** DATA, size_t * DATA_SIZE)
|
||
Returns the value for the entry with given key. If key_size is -1,
|
||
key is assumed to be a null-terminated string. If data_size is
|
||
not NULL, the size of the value is placed into data_size.
|
||
|
||
|
||
-- Function: int cfuhash_exists_data (cfuhash_table_t * HT, const void
|
||
* KEY, size_t KEY_SIZE)
|
||
Returns 1 if an entry with the given key exists in the hash, 0
|
||
otherwise.
|
||
|
||
-- Function: int cfuhash_put_data (cfuhash_table_t * HT, const void *
|
||
KEY, size_t KEY_SIZE, void * DATA, size_t DATA_SIZE, void **
|
||
R)
|
||
Inserts the given data value into the hash and associates it with
|
||
key. If key_size is -1, key is assumed to be a null-terminated
|
||
string. If data_size is -1, it is assumed to be a null-terminated
|
||
string (it's length will be calculated using strlen). If
|
||
data_size is zero, it will be returned as zero when the value is
|
||
requested.
|
||
|
||
|
||
-- Function: void cfuhash_clear (cfuhash_table_t * HT)
|
||
Clears the hash table (deletes all entries).
|
||
|
||
-- Function: void * cfuhash_delete_data (cfuhash_table_t * HT, const
|
||
void * KEY, size_t KEY_SIZE)
|
||
Deletes the entry in the hash associated with key. If the entry
|
||
existed, it's value will be returned.
|
||
|
||
|
||
-- Function: void **cfuhash_keys_data (cfuhash_table_t * HT, size_t *
|
||
NUM_KEYS, size_t ** KEY_SIZES, int FAST)
|
||
Returns all the keys from the hash. The number of keys is placed
|
||
into the value pointed to by num_keys. If key_sizes is not NULL,
|
||
it will be set to an array of key sizes. If fast is zero, copies
|
||
of the keys are returned. Otherwise, pointers to the real keys
|
||
will be returned.
|
||
|
||
|
||
-- Function: int cfuhash_each_data (cfuhash_table_t * HT, void ** KEY,
|
||
size_t * KEY_SIZE, void ** DATA, size_t * DATA_SIZE)
|
||
Initializes a loop over all the key/value pairs in the hash. It
|
||
returns the first key/value pair (see cfuhash_next_data()). 1 is
|
||
returned if there are any entries in the hash. 0 is returned
|
||
otherwise.
|
||
|
||
|
||
-- Function: int cfuhash_next_data (cfuhash_table_t * HT, void ** KEY,
|
||
size_t * KEY_SIZE, void ** DATA, size_t * DATA_SIZE)
|
||
Gets the next key/value pair from the hash. You must initialize
|
||
the loop using cfuhash_each_data() before calling this function.
|
||
If a entry is left to return, 1 is returned from the function. 0
|
||
is returned if there are no more entries in the hash.
|
||
|
||
|
||
-- Function: size_t cfuhash_foreach_remove (cfuhash_table_t * HT,
|
||
cfuhash_remove_fn_t R_FN, cfuhash_free_fn_t FF, void * ARG)
|
||
Iterates over the key/value pairs in the hash, passing each one
|
||
to r_fn, and removes all entries for which r_fn returns true. If
|
||
ff is not NULL, it is the passed the data to be freed. arg is
|
||
passed to r_fn.
|
||
|
||
|
||
-- Function: size_t cfuhash_foreach (cfuhash_table_t * HT,
|
||
cfuhash_foreach_fn_t FE_FN, void * ARG)
|
||
Iterates over the key/value pairs in the hash, passing each one
|
||
to fe_fn, along with arg. This locks the hash, so do not call any
|
||
operations on the hash from within fe_fn unless you really know
|
||
what you're doing.
|
||
|
||
If the return value from fe_fn() is not zero, the iteration stops.
|
||
|
||
|
||
-- Function: int cfuhash_destroy (cfuhash_table_t * HT)
|
||
Frees all resources allocated by the hash.
|
||
|
||
|
||
-- Function: int cfuhash_destroy_with_free_fn (cfuhash_table_t * HT,
|
||
cfuhash_free_fn_t FF)
|
||
Frees all resources allocated by the hash. If ff is not NULL, it
|
||
is called for each hash entry with the value of the entry passed as
|
||
its only argument. If ff is not NULL, it overrides any function
|
||
set previously with cfuhash_set_free_function().
|
||
|
||
|
||
-- Function: int cfuhash_rehash (cfuhash_table_t * HT)
|
||
Rebuild the hash to better accomodate the number of entries. See
|
||
cfuhash_set_thresholds().
|
||
|
||
|
||
-- Function: size_t cfuhash_num_entries (cfuhash_table_t * HT)
|
||
Returns the number entries in the hash.
|
||
|
||
-- Function: size_t cfuhash_num_buckets (cfuhash_table_t * HT)
|
||
Returns the number of buckets allocated for the hash.
|
||
|
||
-- Function: size_t cfuhash_num_buckets_used (cfuhash_table_t * HT)
|
||
Returns the number of buckets actually used out of the total number
|
||
allocated for the hash.
|
||
|
||
|
||
-- Function: char * cfuhash_bencode_strings (cfuhash_table_t * HT)
|
||
Assumes all the keys and values are null-terminated strings and
|
||
returns a bencoded string representing the hash (see
|
||
http://www.bittorrent.com/protocol.html)
|
||
|
||
|
||
-- Function: int cfuhash_lock (cfuhash_table_t * HT)
|
||
Locks the hash. Use this with the each and next functions for
|
||
concurrency control. Note that the hash is locked automatically
|
||
when doing inserts and deletes, so if you lock the hash and then
|
||
try to insert something into it, you may get into a deadlock,
|
||
depending on your system defaults for how mutexes work.
|
||
|
||
|
||
-- Function: int cfuhash_unlock (cfuhash_table_t * HT)
|
||
Unlocks the hash. Use this with the each an next functions for
|
||
concurrency control. The caveat for cfuhash_lock() also applies to
|
||
this function.
|
||
|
||
|
||
-- Function: int cfuhash_pretty_print (cfuhash_table_t * HT, FILE * FP)
|
||
Pretty print the hash's key/value pairs to the stream fp. It is
|
||
assumed that all the keys and values are null-terminated strings.
|
||
|
||
|
||
These are like the _data versions of these functions, with the
|
||
following exceptions:
|
||
|
||
1) They assume that the key provided is a null-terminated string.
|
||
|
||
2) They don't worry about the size of the data.
|
||
|
||
3) Returned keys or values are the return value of the function.
|
||
|
||
-- Function: void * cfuhash_get (cfuhash_table_t * HT, const char *
|
||
KEY)
|
||
|
||
-- Function: int cfuhash_exists (cfuhash_table_t * HT, const char *
|
||
KEY);
|
||
|
||
-- Function: void * cfuhash_put (cfuhash_table_t * HT, const char *
|
||
KEY, void * DATA);
|
||
|
||
-- Function: void * cfuhash_delete (cfuhash_table_t * HT, const char *
|
||
KEY);
|
||
|
||
-- Function: int cfuhash_each (cfuhash_table_t * HT, char ** KEY, void
|
||
** DATA);
|
||
|
||
-- Function: int cfuhash_next (cfuhash_table_t * HT, char ** KEY, void
|
||
** DATA);
|
||
|
||
-- Function: void ** cfuhash_keys (cfuhash_table_t * HT, size_t *
|
||
NUM_KEYS, int FAST);
|
||
|
||
Valid flags for cfuhash_new() or cfuhash_set_flag):
|
||
|
||
-- CFUHASH_NOCOPY_KEYS:
|
||
Don't copy the key when adding an entry to the hash table.
|
||
|
||
-- CFUHASH_NO_LOCKING:
|
||
Don't not use any mutexes. Beware that this flag makes the hash
|
||
table non thread-safe.
|
||
|
||
-- CFUHASH_FROZEN:
|
||
Do not rehash (don't grow or shrink the number of buckets in the
|
||
hash table when the thresholds are reached).
|
||
|
||
-- CFUHASH_FROZEN_UNTIL_GROWS:
|
||
Do not rehash until the upper threshold is reached the first time
|
||
(useful for preallocating a large hash to avoid rehashing while
|
||
filling it).
|
||
|
||
-- CFUHASH_FREE_DATA:
|
||
Call free() on the values when cfuhash_destroy() is called.
|
||
|
||
-- CFUHASH_IGNORE_CASE:
|
||
Treat the keys case-insensitively.
|
||
|
||
|
||
File: libcfu.info, Node: Linked list, Next: Strings, Prev: Hash table, Up: Data structures
|
||
|
||
1.2 Linked list
|
||
===============
|
||
|
||
-- Special Form: typedef int (*cfulist_foreach_fn_t)(void * DATA,
|
||
size_t DATA_SIZE, void * ARG)
|
||
Function called for each element in the list when passed to
|
||
cfulist_foreach(). A non-zero return value means to stop
|
||
iteration.
|
||
|
||
-- Special Form: typedef void * (*cfulist_map_fn_t)(void *DATA, size_t
|
||
DATA_SIZE, void *ARG, size_t *NEW_DATA_SIZE)
|
||
Function called for each element in the list when passed to
|
||
cfulist_map(). The return value is used to build a new list.
|
||
|
||
-- Special Form: typedef void (*cfulist_free_fn_t)(void * DATA)
|
||
Function called to free the data in an element.
|
||
|
||
-- Function: cfulist_t * cfulist_new ();
|
||
Returns a new list.
|
||
|
||
-- Function: size_t cfulist_num_entries (cfulist_t *LIST)
|
||
Returns the number of entries in the list.
|
||
|
||
|
||
-- Function: int cfulist_push_data (cfulist_t * LIST, void * DATA,
|
||
size_t DATA_SIZE)
|
||
Push a value onto the end of the list.
|
||
|
||
-- Function: int cfulist_pop_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE)
|
||
Pop a value from the end of the list (removing it from the list).
|
||
|
||
-- Function: int cfulist_unshift_data (cfulist_t * LIST, void * DATA,
|
||
size_t DATA_SIZE)
|
||
Add a value at the beginning of the list.
|
||
|
||
-- Function: int cfulist_shift_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE)
|
||
Shift a value off the beginning of the list.
|
||
|
||
-- Function: int cfulist_enqueue_data (cfulist_t * LIST, void * DATA,
|
||
size_t DATA_SIZE)
|
||
Add a value at the end of the queue (equivalent to push)
|
||
|
||
-- Function: int cfulist_dequeue_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE)
|
||
Remove the value at the beginning of the list (equivalent to
|
||
shift).
|
||
|
||
-- Function: int cfulist_first_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE);
|
||
Return the first entry from the list (without removing it from the
|
||
list).
|
||
|
||
-- Function: int cfulist_last_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE);
|
||
Return the last entry from the list (without removing it from the
|
||
list).
|
||
|
||
-- Function: int cfulist_nth_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE, size_t N);
|
||
Return the nth entry from the list (without removing it from the
|
||
list). n starts at zero.
|
||
|
||
-- Function: void cfulist_reset_each (cfulist_t * LIST);
|
||
|
||
-- Function: int cfulist_each_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE);
|
||
|
||
-- Function: int cfulist_next_data (cfulist_t * LIST, void ** DATA,
|
||
size_t * DATA_SIZE);
|
||
|
||
-- Function: size_t cfulist_foreach (cfulist_t * LIST,
|
||
cfulist_foreach_fn_t FE_FN, void * ARG);
|
||
Calls fe_fn() for each element in the list. Also passes arg on each
|
||
call. Do not try to manipulate the list inside fe_fn(), as the
|
||
list will be locked.
|
||
|
||
If fe_fn() returns a non-zero value, the iteration over the
|
||
elements stops.
|
||
|
||
-- Function: cfulist_t * cfulist_map (cfulist_t *LIST,
|
||
cfulist_map_fn_t MAP_FN, void *ARG);
|
||
Creates a new list from the list passed in. Calls map_fn() on each
|
||
element in the list. The return value is placed in the
|
||
corresponding position in the new list.
|
||
|
||
-- Function: void cfulist_destroy (cfulist_t * LIST)
|
||
Free all resources used by the list.
|
||
|
||
-- Function: void cfulist_destroy (cfulist_t * LIST, cfulist_free_fn_t
|
||
FREE_FN)
|
||
Free all resources used by the list. If free_fn is not NULL, call
|
||
it for each element of the list, passing the data to it as a void
|
||
*.
|
||
|
||
When you don't care about the size of the data
|
||
|
||
-- Function: int cfulist_push (cfulist_t * LIST, void * DATA)
|
||
|
||
-- Function: void * cfulist_pop (cfulist_t * LIST);
|
||
|
||
-- Function: int cfulist_unshift (cfulist_t * LIST, void * DATA);
|
||
|
||
-- Function: void * cfulist_shift (cfulist_t * LIST);
|
||
|
||
-- Function: int cfulist_enqueue (cfulist_t * IST, void * DATA);
|
||
|
||
-- Function: void * cfulist_dequeue (cfulist_t * LIST);
|
||
|
||
Strings - assume data is a null-terminated string - size is
|
||
calculated by strlen(data) + 1
|
||
|
||
-- Function: int cfulist_push_string (cfulist_t * LIST, char * DATA)
|
||
|
||
-- Function: char * cfulist_pop_string (cfulist_t * LIST);
|
||
|
||
-- Function: int cfulist_unshift_string (cfulist_t * LIST, char *
|
||
DATA);
|
||
|
||
-- Function: char * cfulist_shift_string (cfulist_t * LIST);
|
||
|
||
-- Function: int cfulist_enqueue_string (cfulist_t * LIST, char *
|
||
DATA);
|
||
|
||
-- Function: char * cfulist_dequeue_string (cfulist_t * LIST);
|
||
|
||
-- Function: char * cfulist_join (cfulist_t * LIST, const char *
|
||
DELIMITER)
|
||
|
||
|
||
File: libcfu.info, Node: Strings, Prev: Linked list, Up: Data structures
|
||
|
||
1.3 Strings
|
||
===========
|
||
|
||
-- Function: cfustring_t * cfustring_new (size_t INITIAL_SIZE)
|
||
Returns a new String.
|
||
|
||
-- Function: cfustring_t * cfustring_new_from_string (const char *
|
||
STRING)
|
||
Returns a new String initalized with the given string.
|
||
|
||
-- Function: int cfustring_dup (cfustring_t * CFU_STR, const char *
|
||
STRING)
|
||
Overwrite anything currently in cfu_str with string.
|
||
|
||
-- Function: int cfustring_clear (cfustring_t * CFU_STR)
|
||
Truncate the string.
|
||
|
||
-- Function: int cfustring_append (cfustring_t * CFU_STR, const char *
|
||
STR)
|
||
Append str to the end of the buffer in cfu_str.
|
||
|
||
-- Function: char * cfustring_get_buffer (cfustring_t * CFU_STR)
|
||
Get the buffer used to hold the string. Do not free() it, as it is
|
||
used directly by cfustring and will be destroyed when
|
||
cfustring_destroy() is called.
|
||
|
||
|
||
-- Function: char * cfustring_get_buffer_copy (cfustring_t * CFU_STR)
|
||
Same as cfustring_get_buffer(), except return a copy of the string.
|
||
Caller is responsible for deallocating the buffer with free().
|
||
|
||
|
||
-- Function: cfustring_t ** cfustring_split (cfustring_t * CFU_STR,
|
||
size_t * NUM_STRINGS, size_t LIMIT, ...)
|
||
Split cfu_str on one or more delimiting strings, e.g.,
|
||
cfustring_split(cfu_str, 2, 0, "\r\n", "\n"). Use a limit > 0 if
|
||
you want to only get back a certain number of strings and ignore
|
||
any extra delimiters.
|
||
|
||
|
||
-- Function: char ** cfustring_split_to_c_str (cfustring_t * CFU_STR,
|
||
size_t * NUM_STRINGS, size_t LIMIT, ...)
|
||
Same as cfustring_split(), except return an array of C-strings.
|
||
Caller is responsible for deallocating the buffers.
|
||
|
||
|
||
-- Function: int cfustring_destroy (cfustring_t * CFU_STR)
|
||
Free all resources allocated by cfu_str.
|
||
|
||
-- Function: char * cfustring_dup_c_str (const char * STR)
|
||
Duplicate the C string str. Caller must free with free().
|
||
|
||
-- Function: char * cfustring_dup_c_str_n (const char * STR, size_t N)
|
||
Same as cfustring_dup_c_str(), but only copy at most n chars
|
||
|
||
-- Function: size_t cfustring_sprintf (cfustring_t * CFU_STR, const
|
||
char * FMT, ...);
|
||
Like sprintf(), but writes to a self-extending string.
|
||
|
||
-- Function: size_t cfustring_vsprintf (cfustring_t * CFU_STR, const
|
||
char * FMT, va_list AP);
|
||
Like vsprintf(), but writes to a self-extending string.
|
||
|
||
-- Function: char * cfustring_sprintf_c_str (const char * FMT, ...)
|
||
Similar to sprintf(), but allocates a C string of the appropriate
|
||
size for you and returns it.
|
||
|
||
-- Function: char ** cfustring_c_str_split (const char * C_STR, size_t
|
||
* NUM_STRINGS, size_t LIMIT, ...)
|
||
Like cfustring_split_to_c_str(), but split a char * instead of a
|
||
cfustring_t *.
|
||
|
||
|
||
|
||
File: libcfu.info, Node: Conf, Next: Options, Prev: Top, Up: Top
|
||
|
||
2 Conf
|
||
******
|
||
|
||
This needs to be better documented.
|
||
|
||
Apache-style conf files contain directives and containers.
|
||
Directives are simple one line specifications with or without
|
||
arguments, e.g.,
|
||
|
||
Doit Expires On LoadModule my_mod modules/my_mod.so
|
||
|
||
Containers have a type and a name associated with them and they in
|
||
turn contain directives and/or containers, e.g.,
|
||
|
||
<MyContainer test1> Expires Off <DB devdb>
|
||
DBHost db.example.com DBUser
|
||
test_user </DB> </MyContainer>
|
||
|
||
Values may be quoted, e.g.
|
||
|
||
DBUser "test user"
|
||
|
||
But must be specified on a single line. To escape quotes within a
|
||
quoted string, use the '\' character.
|
||
|
||
-- Function: int cfuconf_parse_file (char * FILE_PATH, cfuconf_t **
|
||
CONF, char ** ERROR)
|
||
Parse the apache-like conf file specified by file_path, returning
|
||
a pointer to a cfuconf_t structure in conf. Returns zero on
|
||
success, less than zero on error. If an error occurs and error
|
||
is not NULL, it will be set to an error message (which must be
|
||
free()'d by the caller).
|
||
|
||
|
||
-- Function: int cfuconf_parse_buffer (char * BUFFER, cfuconf_t **
|
||
CONF, char ** ERROR)
|
||
Same as cfuconf_parse_file(), except assume the contents of the
|
||
file are already in buffer.
|
||
|
||
|
||
-- Function: void cfuconf_destroy (cfuconf_t * CONF)
|
||
Free all resources used by the cfuconf_t structure
|
||
|
||
-- Function: cfuhash_table_t * cfuconf_get_containers (cfuconf_t *
|
||
CONF)
|
||
Get a hash of containers at the top level of conf
|
||
|
||
-- Function: cfuhash_table_t * cfuconf_get_directives (cfuconf_t *
|
||
CONF)
|
||
Get a hash of directives at the to level
|
||
|
||
-- Function: int cfuconf_get_directive_one_arg (cfuconf_t * CONF, char
|
||
* DIRECTIVE, char ** RVALUE)
|
||
Get the value of the given directive, assuming there is only one
|
||
argument
|
||
|
||
-- Function: int cfuconf_get_directive_two_args (cfuconf_t * CONF,
|
||
char * DIRECTIVE, char ** RVALUE, char ** RVALUE2)
|
||
Get the value of the given directive, assuming there are two
|
||
arguments
|
||
|
||
-- Function: int cfuconf_get_directive_n_args (cfuconf_t * CONF, char
|
||
* DIRECTIVE, size_t N, ...)
|
||
Get the value of the given directives, with n arguments
|
||
|
||
|
||
File: libcfu.info, Node: Options, Next: Thread queue, Prev: Conf, Up: Top
|
||
|
||
3 Options
|
||
*********
|
||
|
||
Command-line arguments can be parsed with the following:
|
||
|
||
|
||
cfuopt_t *opt = cfuopt_new();
|
||
cfuopt_add_entry(opt, "verbose|v!", &verbose, "Verbosity", "");
|
||
cfuopt_add_entry(opt, "file|f:s", &file, "File to load", "FILE");
|
||
cfuopt_add_entry(opt, "count|c|n=i", &count, "Count to run", "COUNT");
|
||
cfuopt_add_entry(opt, "scale|s:f", &scale, "Scaling factor", "SCALE");
|
||
cfuopt_parse(opt, &argc, &argv, &error);
|
||
/* do stuff here with the options */
|
||
cfuopt_destroy(opt);
|
||
free(file);
|
||
|
||
-- Function: cfuopt_t * cfuopt_new ()
|
||
Returns a new options context.
|
||
|
||
-- Function: void cfuopt_add_entry (cfuopt_t *CONTEXT, const char
|
||
*OPT_STR, void *ARG_DATA, const char *DESCRIPTION, const char
|
||
*ARG_DESCRIPTION)
|
||
Adds to the list of known options.
|
||
|
||
-- Function: void cfuopt_parse (cfuopt_t *CONTEXT, int *ARGC, char
|
||
***ARGV, char **ERROR)
|
||
Parses the command line and modifies argc and argv to account for
|
||
left over arguments.
|
||
|
||
-- Function: char * cfuopt_get_help_str (cfuopt_t *CONTEXT)
|
||
Returns a help string built from the entries added with
|
||
cfuopt_add_entry().
|
||
|
||
-- Function: void cfuopt_destroy (cfuopt_t *CONTEXT)
|
||
Frees up resources used by the option parser.
|
||
|
||
|
||
File: libcfu.info, Node: Thread queue, Next: Timer, Prev: Options, Up: Top
|
||
|
||
4 Thread queue
|
||
**************
|
||
|
||
cfuthread_queue provides a way to serialize requests for a resource
|
||
where you want the resource to be accessed from a single thread only.
|
||
For instance, for a database connection where making calls in separate
|
||
threads does not work properly, you can use cfuthread_queue.
|
||
cfuthread_queue_new() creates a new thread that waits for something to
|
||
be added to the queue. Once something is added, the thread will
|
||
process the data by calling the function you pass as an argument to the
|
||
cfuthread_queue_new() function.
|
||
|
||
-- Function: cfuthread_queue_t * cfuthread_queue_new
|
||
(cfuthread_queue_fn_t FN)
|
||
Creates a new thread queue structure that will run the given
|
||
function when a request is received.
|
||
|
||
|
||
-- Function: cfuthread_queue_t * cfuthread_queue_new_with_cleanup
|
||
(cfuthread_queue_fn_t FN, cfuthread_queue_init_t INIT_FN,
|
||
void * INIT_ARG, cfuthread_queue_cleanup_t CLEANUP_FN, void *
|
||
CLEANUP_ARG)
|
||
Same as cfuthread_queue_new(), but with an initialization
|
||
function that gets called with the argument init_arg when the
|
||
thread is created, and a cleanup function that gets called with
|
||
the argument cleanup_arg when the thread exits, e.g., when
|
||
cfuthread_queue_destroy() is called.
|
||
|
||
|
||
-- Function: void * cfuthread_queue_make_request (cfuthread_queue_t *
|
||
TQ, void * DATA)
|
||
Add a request to the queue. data will get passed to the function
|
||
fn given to cfuthread_queue_new when it reaches the front of the
|
||
queue.
|
||
|
||
|
||
-- Function: void cfuthread_queue_destroy (cfuthread_queue_t * TQ)
|
||
Free up resources used by the queue, in addition to canceling the
|
||
thread.
|
||
|
||
|
||
|
||
File: libcfu.info, Node: Timer, Next: License, Prev: Thread queue, Up: Top
|
||
|
||
5 Timer
|
||
*******
|
||
|
||
-- Function: cfutime_t *cfutime_new ();
|
||
Return a new cfutime structure.
|
||
|
||
-- Function: void cfutime_begin (cfutime_t *TIME)
|
||
Start the timer.
|
||
|
||
-- Function: void cfutime_end (cfutime_t * TIME)
|
||
Stop the timer.
|
||
|
||
-- Function: double cfutime_elapsed (cfutime_t * TIME)
|
||
Return the number of seconds elapsed as a double.
|
||
|
||
-- Function: void cfutime_free (cfutime_t * TIME)
|
||
Deallocate resources allocated for time.
|
||
|
||
|
||
File: libcfu.info, Node: License, Prev: Timer, Up: Top
|
||
|
||
License
|
||
*******
|
||
|
||
Copyright (C) 2005 Don Owens All rights reserved.
|
||
|
||
This code is released under the BSD license:
|
||
|
||
Redistribution and use in source and binary forms, with or without
|
||
modification, are permitted provided that the following conditions are
|
||
met:
|
||
|
||
* Redistributions of source code must retain the above copyright
|
||
notice, this list of conditions and the following disclaimer.
|
||
|
||
* Redistributions in binary form must reproduce the above
|
||
copyright notice, this list of conditions and the following
|
||
disclaimer in the documentation and/or other materials provided with
|
||
the distribution.
|
||
|
||
* Neither the name of the author nor the names of its
|
||
contributors may be used to endorse or promote products derived from
|
||
this software without specific prior written permission.
|
||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
||
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
||
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
||
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
||
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
||
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
||
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
||
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
||
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
||
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||
|
||
|
||
File: libcfu.info, Node: Concept index, Next: Function index, Prev: Top, Up: Top
|
||
|
||
Concept index
|
||
*************
|
||
|
||
|