---

misc.h File Reference

Miscellaneous utility functions. More...

#include <stdio.h>
#include <string.h>
#include <stddef.h>
#include "gale/types.h"
#include "gale/core.h"
#include "oop.h"

Go to the source code of this file.

Compounds
struct	gale_text_accumulator
Memory Management
#define	gale_create(x)    ((x) = gale_malloc(sizeof(*(x))))
	Allocate an object. More...
#define	gale_create_array(x,count)    ((x) = gale_malloc(sizeof(*(x)) * (count)))
	Allocate an array of objects. More...
#define	gale_resize_array(x,count)    ((x) = gale_realloc(x,sizeof(*(x)) * (count)))
	Resize an array of objects. More...
void*	gale_malloc (size_t size)
	Allocate memory. More...
void*	gale_malloc_atomic (size_t size)
	Allocate memory that will never contain pointers.
void*	gale_malloc_safe (size_t size)
	Allocate memory that will never be garbage-collected.
void*	gale_realloc (void *mem,size_t len)
	Resize a block of memory. More...
void	gale_free (void *)
	Free a block of memory. More...
void	gale_finalizer (void *ptr,void (*fun)(void *ptr,void *user),void *user)
	Register a finalizer to be called when memory is garbage collected. More...
void	gale_check_mem (void)
	Check the heap. More...
struct gale_data	gale_data_copy (struct gale_data data)
	Duplicate a region of memory. More...
int	gale_data_compare (struct gale_data a,struct gale_data b)
	Compare two memory blocks, a la memcmp(). More...
struct gale_ptr*	gale_make_weak (void *ptr)
	Create a weak pointer. More...
struct gale_ptr*	gale_make_ptr (void *)
	Create a normal pointer that looks like a weak pointer. More...
void*	gale_get_ptr (struct gale_ptr *wp)
	Dereference a weak pointer. More...
const struct gale_data	null_data = { NULL, 0 }
	The zero-length block of memory.
String Processing
Functions for manipulating gale_text objects. Strings in Gale are represented by constant, garbage-collected arrays of wchar_t. The functions here create and manipulate these arrays.
#define	G_(x)    (_gale_text_literal(L##x,sizeof(L##x) / sizeof(wch) - 1))
	Use this macro for literal Unicode text strings. More...
struct gale_text	_gale_text_literal (const wchar_t *,size_t len)
struct gale_text	gale_text_concat (int count,...)
	Concatenate text strings. More...
struct gale_text	gale_text_concat_array (int count,struct gale_text *array)
	Concatenate an array of text strings. More...
void	gale_text_accumulate (struct gale_text_accumulator *,struct gale_text)
	Append text to an accumulator. More...
int	gale_text_accumulator_empty (const struct gale_text_accumulator *)
	Return nonzero if an accumulator contains any text. More...
struct gale_text	gale_text_collect (const struct gale_text_accumulator *)
	Return the text collected in an accumulator. More...
struct gale_text	gale_text_left (struct gale_text,int len)
	Extract the leftmost substring of len characters. More...
struct gale_text	gale_text_right (struct gale_text,int len)
	Extract the rightmost substring of len characters. More...
int	gale_text_token (struct gale_text string,wch sep,struct gale_text *token)
	Divide a string into tokens using the separator character 'sep'. More...
struct gale_text	gale_text_replace ( struct gale_text original, struct gale_text find, struct gale_text replace)
	Replace one substring with another, everywhere it appears. More...
int	gale_text_compare (struct gale_text a,struct gale_text b)
	Compare two strings, a la strcmp(). More...
int	gale_text_to_number (struct gale_text str)
	Parse a number. More...
struct gale_text	gale_text_from_number (int n,int base,int pad)
	Create a text representation of a number. More...
struct gale_data	gale_text_as_data (struct gale_text)
	View the contexts of a text string as opaque binary data. More...
struct gale_text	gale_text_from_data (struct gale_data)
	Convert opaque binary data back into a text string. More...
struct gale_encoding*	gale_make_encoding (struct gale_text enc)
	Initialize a character encoding translator. More...
struct gale_text	gale_text_from (struct gale_encoding *enc,const char *str,int len)
	Convert some character encoding into a Unicode string. More...
char*	gale_text_to (struct gale_encoding *enc,struct gale_text str)
	Convert a Unicode string to some character encoding. More...
const struct gale_text	null_text = { NULL, 0 }
	The empty string.
const struct gale_text_accumulator	null_accumulator = { 0, }
	An empty accumulator which you can use to initialize new accumulators.
Data Serialization
Pack and unpack data structures. Most libgale clients will never have to use these functions directly. They are used to serialize and deserialize data from binary streams (mostly to support network protocols). For a particular data encoding "type", there are usually three functions defined: int gale_unpack_type(struct gale_data *,type *) void gale_pack_type(struct gale_data *,type); size_t gale_type_size(type) The gale_unpack_type function converts binary data into the specified type, modifying the gale_data structure to start at the end of the decoded data, returning nonzero iff the operation was successful. The gale_pack_type function does the opposite, converting the specified type into binary data. Space must be preallocated in the gale_data structure for the data; the gale_type_size function supplies a conservative (but usually accurate) estimate of the amount of space needed to store a particular value.
#define	gale_copy_size(s)    (s)
#define	gale_skip_size(sz)    ((sz) + gale_u32_size())
#define	gale_rle_size(s)    (((s)+127)/128+(s))
#define	gale_u32_size()    (sizeof(u32))
#define	gale_wch_size()    (sizeof(u16))
#define	gale_str_size(t)    (strlen(t) + 1)
#define	gale_text_size(t)    (gale_text_len_size(t) + gale_u32_size())
#define	gale_text_len_size(t)    ((t).l * gale_wch_size())
#define	gale_time_size()    (sizeof(u32) * 4)
int	gale_unpack_copy (struct gale_data *,void *,size_t)
int	gale_unpack_compare (struct gale_data *,const void *,size_t)
void	gale_pack_copy (struct gale_data *,const void *,size_t)
int	gale_unpack_skip (struct gale_data *)
void	gale_pack_skip (struct gale_data *,size_t)
int	gale_unpack_rle (struct gale_data *,void *,size_t)
void	gale_pack_rle (struct gale_data *,const void *,size_t)
int	gale_unpack_u32 (struct gale_data *,u32 *)
void	gale_pack_u32 (struct gale_data *,u32)
int	gale_unpack_wch (struct gale_data *,wch *)
void	gale_pack_wch (struct gale_data *,wch)
int	gale_unpack_str (struct gale_data *,const char **)
void	gale_pack_str (struct gale_data *,const char *)
int	gale_unpack_text (struct gale_data *,struct gale_text *)
void	gale_pack_text (struct gale_data *,struct gale_text)
int	gale_unpack_text_len (struct gale_data *,size_t len, struct gale_text *)
void	gale_pack_text_len (struct gale_data *,struct gale_text)
int	gale_unpack_time (struct gale_data *,struct gale_time *)
void	gale_pack_time (struct gale_data *,struct gale_time)
int	gale_unpack_fragment (struct gale_data *,struct gale_fragment *)
void	gale_pack_fragment (struct gale_data *,struct gale_fragment)
size_t	gale_fragment_size (struct gale_fragment)
int	gale_unpack_group (struct gale_data *,struct gale_group *)
void	gale_pack_group (struct gale_data *,struct gale_group)
size_t	gale_group_size (struct gale_group)
Error Reporting
typedef void*	gale_call_error (int severity,struct gale_text msg,void *user)
	Function type for a user-defined error handler. More...
enum	gale_error {   GALE_NOTICE,   GALE_WARNING,   GALE_ERROR }
	Degree of error severity for gale_alert().
void	gale_alert (int severity,struct gale_text str,int err)
	Report an error; terminate if severity is GALE_ERROR. More...
void	gale_on_error (oop_source *oop,gale_call_error *func,void *user)
	Set a different error handler. More...
Connection Management
Asynchronous TCP connection management for liboop.
typedef void*	gale_connect_call (int fd, struct gale_text hostname,struct sockaddr_in addr, int found_local,void *user)
	Callback when a connection completes. More...
struct gale_text	gale_connect_text (struct gale_text host,struct sockaddr_in)
	Return a description of the connected host. More...
struct gale_connect*	gale_make_connect ( oop_source *source,struct gale_text host,int avoid_local_port, gale_connect_call *,void *)
	Start attempting to establish a TCP connection. More...
void	gale_abort_connect (struct gale_connect *)
	Abort a connection attempt. More...
Terminal Output
enum	gale_print_flags {   gale_print_bold = 1,   gale_print_clobber_left = 2,   gale_print_clobber_right = 4 }
	Flags to control the formatting of gale_print() output. More...
void	gale_print (FILE *fp,int attr,struct gale_text str)
	Safely output a string to the console. More...
void	gale_print_line (FILE *fp,int attr,struct gale_text)
	Write a string to the console and advance to a new line. More...
int	gale_column (int start,wch)
int	gale_text_width (struct gale_text str)
	Measure the width of a string, counting doublewidth CJK glyphs. More...
void	gale_beep (FILE *fp)
	Ring the terminal bell. More...
int	gale_columns (FILE *fp)
	Get the width of a terminal. More...
struct gale_text	gale_read_line (FILE *fp)
	Read a line of text from a file descriptor, using readline if appropriate. More...
Process Management
void	gale_exec (oop_source *,struct gale_text prog, int count,const struct gale_text *, int *in,int *out, int (*)(int count,const struct gale_text *,void *user), void *(*)(int status,void *user), void *user)
void	gale_restart (void)
	Restart the running program. More...
void	gale_kill (struct gale_text class,int do_kill)
	There can be only one. More...
void	gale_cleanup (void (*cleanup)(void *),void *)
	Register a cleanup function. More...
void	gale_do_cleanup ()
	Call cleanup functions. More...
void	gale_watch_tty (oop_source *oop,int fd)
	Deathpolling. More...
void	gale_daemon (oop_source *)
	Daemonize (go into the background). More...
void	gale_detach (oop_source *)
	Detach from the terminal (like galed but unlike gsub). More...
Map
struct gale_map*	gale_make_map (int weak)
	Create a key-value lookup table. More...
void	gale_map_add (struct gale_map *map,struct gale_data key,void *data)
	Add a key-value pair to a map. More...
void*	gale_map_find (const struct gale_map *map,struct gale_data key)
	Find an entry by its key. More...
int	gale_map_walk (const struct gale_map *map,const struct gale_data *after, struct gale_data *key,void **data)
	Traverse a map in order. More...
Time Processing
struct gale_time	gale_time_zero (void)
	The "beginning of time".
struct gale_time	gale_time_now (void)
	The current time.
struct gale_time	gale_time_forever (void)
	The "end of time".
struct gale_time	gale_time_seconds (int sec)
	A time representing sec seconds from the epoch.
int	gale_time_compare (struct gale_time a,struct gale_time b)
	Compare two time values. More...
struct gale_time	gale_time_diff (struct gale_time a,struct gale_time b)
	Subtract two time values. More...
struct gale_time	gale_time_add (struct gale_time a,struct gale_time b)
	Add two time values. More...
void	gale_time_to (struct timeval *tv,struct gale_time time)
	Convert a time value to the Unix timeval structure. More...
void	gale_time_from (struct gale_time *time,const struct timeval *tv)
	Convert a Unix timeval structure to a time value. More...
struct gale_text	gale_time_format (struct gale_time time)
	Format a time value as text. More...
Fragment and Group Management
Functions for manipulating gale_group and gale_fragment objects. Gale messages (and other data structures) are built out of gale_fragment objects (which are named values) and gale_group objects (which are collections of fragments). These are similar to LISP 'alists'.
struct gale_group	gale_group_empty (void)
	Return the empty group.
void	gale_group_add (struct gale_group *group,struct gale_fragment frag)
	Add a new fragment to an existing group. More...
void	gale_group_append (struct gale_group *a,struct gale_group b)
	Concatenate two groups. More...
struct gale_group	gale_group_find (struct gale_group, struct gale_text name, enum gale_fragment_type)
	You probably don't need this, use gale_group_lookup() instead.
int	gale_group_remove (struct gale_group *group, struct gale_text name, enum gale_fragment_type type)
	Remove a fragment from a group. More...
void	gale_group_replace (struct gale_group *group,struct gale_fragment frag)
	Add a fragment to an existing group, replacing any others with the same name. More...
int	gale_group_null (struct gale_group)
	Return nonzero if the specified group is empty.
struct gale_fragment	gale_group_first (struct gale_group)
	Return the first fragment in the specified group. More...
struct gale_group	gale_group_rest (struct gale_group)
	Return the group consisting of all the fragments except the first. More...
void	gale_group_prefix (struct gale_group *,struct gale_group tail)
	Do some mysterious thing.
int	gale_group_lookup ( struct gale_group group,struct gale_text name, enum gale_fragment_type type, struct gale_fragment *frag)
	Find a fragment in a group by name. More...
struct gale_text	gale_print_fragment (struct gale_fragment,int indent)
	Return a human-readable version of the fragment (for debugging).
struct gale_text	gale_print_group (struct gale_group,int indent)
	Return a human-readable version of the group (for debugging).
int	gale_fragment_compare (struct gale_fragment a,struct gale_fragment b)
	Compare two fragments. More...
int	gale_group_compare (struct gale_group a,struct gale_group b)
	Compare two groups. More...
File and Directory Manipulation
void	make_dir (struct gale_text path,int mode)
	Create a directory. More...
struct gale_text	sub_dir (struct gale_text path,struct gale_text sub)
	Find a subdirectory. More...
struct gale_text	submk_dir (struct gale_text path,struct gale_text sub,int mode)
	Find a subdirectory. More...
struct gale_text	up_dir (struct gale_text path)
	Return the parent directory. More...
struct gale_text	dir_file (struct gale_text path,struct gale_text file)
	Safely construct a pathname from a directory and a filename. More...
struct gale_text	dir_search (struct gale_text name,int cwd,struct gale_text,...)
	Search for a file in a list of directories. More...
struct gale_data	gale_read_from (int fd,int size_limit)
	Read data from a file descriptor. More...
int	gale_write_to (int fd,struct gale_data data)
	Write data to a file descriptor. More...
struct gale_data	gale_read_file ( struct gale_text name, int size_limit,int do_paranoia, struct gale_file_state **state)
	Read data from a disk file. More...
int	gale_write_file ( struct gale_text name, struct gale_data data, int is_private, struct gale_file_state **state)
	Write data to a disk file. More...
int	gale_erase_file (const struct gale_file_state *state)
	Erase a disk file. More...
int	gale_file_changed (const struct gale_file_state *since)
	Check to see if a disk file has changed. More...
struct gale_time	gale_get_file_time (const struct gale_file_state *state)
	Return a file's timestamp. More...
void	gale_set_file_time (struct gale_file_state *state,struct gale_time)
	Set a file's timestamp. More...
Debugging Support
struct gale_text	gale_report_call (void *user)
	Function type for a report generator. More...
struct gale_report*	gale_make_report (struct gale_report *outer)
	Create a new report container. More...
void	gale_report_add (struct gale_report *outer,gale_report_call *func,void *user)
	Add a report handler to a report container. More...
void	gale_report_remove (struct gale_report *,gale_report_call *,void *)
	Remove a report handler from a report container. More...
struct gale_text	gale_report_run (struct gale_report *)
	Generate a report from all the report generators registered with a given report container. More...
void	gale_dprintf (int level,const char *fmt,...)
	Debugging printf. More...
void	gale_diprintf (int level,int indent,const char *fmt,...)
	Debugging printf. More...

---

Detailed Description

Miscellaneous utility functions.

This is code that doesn't have to do with gale per se, but which is generally useful (and, in some cases, required by the API).

---

Define Documentation

#define G_( x )   (_gale_text_literal(L##x,sizeof(L##x) / sizeof(wch) - 1))

Use this macro for literal Unicode text strings. struct gale_text foostr = G_("foo");

#define gale_create( x )   ((x) = gale_malloc(sizeof(*(x))))

Allocate an object. Parameters: x   Uninitialized pointer to an object (will be set). See also: gale_malloc()

#define gale_create_array( x, count )   ((x) = gale_malloc(sizeof(*(x)) * (count)))

Allocate an array of objects. Parameters: x   Uninitialized pointer to an array of objects (will be set). count   The length of the array (in objects). See also: gale_malloc()

#define gale_resize_array( x, count )   ((x) = gale_realloc(x,sizeof(*(x)) * (count)))

Resize an array of objects. Parameters: x   Pointer to an array of objects (will be modified in place). count   The new length of the array (in objects). See also: gale_realloc()

---

Typedef Documentation

typedef void* gale_call_error(int severity,struct gale_text msg,void *user)

Function type for a user-defined error handler. Parameters: severity   The severity of the error. msg   The error message. user   A user-defined parameter. Returns: Liboop continuation code (usually OOP_CONTINUE). See also: gale_on_error()

typedef void* gale_connect_call(int fd, struct gale_text hostname,struct sockaddr_in addr, int found_local,void *user)

Callback when a connection completes. Parameters: fd   File descriptor of completed connection (-1 if failed). hostname   Name of remote host. addr   IP address of remote host. found_local   Nonzero if any of the specified addresses were local. user   User-supplied parameter. Returns: Liboop continuation code (usually OOP_CONTINUE).

---

Enumeration Type Documentation

enum gale_print_flags

Flags to control the formatting of gale_print() output. Enumeration values: gale_print_bold   Highlight text. gale_print_clobber_left   Output text at the left margin. gale_print_clobber_right   Erase after the end of the line.

---

Function Documentation

struct gale_text _gale_text_literal ( const wchar_t * sz, size_t len )

For internal use only.

struct gale_text dir_file ( struct gale_text path, struct gale_text file )

Safely construct a pathname from a directory and a filename. This function combines the directory path and the filename file. This would be a simple concatenation (with a "/"), except that we also make sure that file doesn't contain any backreferences ("../"). This makes it safe to construct filenames from network data in a directory "sandbox". Parameters: path   The directory to contain the file. file   The filename relative to path. Returns: The full name of the file.

struct gale_text dir_search ( struct gale_text fn, int f, struct gale_text, ... )

Search for a file in a list of directories. This function searches for a file named fn relative to each of the directories supplied as arguments. (If f is nonzero, the current directory is also searched.) If the file is found, its full pathname is returned. Parameters: fn   The filename to search for. f   Nonzero to search the current directory (and allow absolute filenames). t   List of directories to search, terminated by null_text. Returns: The full pathname of the file, if it was found; null_text otherwise.

void gale_abort_connect ( struct gale_connect * conn )

Abort a connection attempt. This function stops attempting to establish a connection and releases all resources associated with the connection attempt. Parameters: conn   Connection handle from gale_make_connect(). See also: gale_make_connect()

void gale_alert ( int severity, struct gale_text msg, int err )

Report an error; terminate if severity is GALE_ERROR. Parameters: severity   The severity of the error (from gale_error). msg   The error message to report. err   If nonzero, a system errno value to look up.

void gale_beep ( FILE * fp )

Ring the terminal bell. Parameters: fp   Usually stdout or stderr.

void gale_check_mem ( void )

Check the heap. For debugging. Call this if you're worried the heap might be corrupt.

void gale_cleanup ( void(* func)(void *), void * data )

Register a cleanup function. The cleanup function will be called, if at all possible, when the program exits (normally or via most signals). Parameters: cleanup   The function to call on exit.

int gale_column ( int col, wch ch )

Deprecated: Use gale_text_width() instead.

int gale_columns ( FILE * fp )

Get the width of a terminal. Parameters: fp   Usually stdout or stderr. Returns: The number of character positions per line.

struct gale_text gale_connect_text ( struct gale_text host, struct sockaddr_in )

Return a description of the connected host. Parameters: host   Hostname (usually as passed to gale_make_connect()). addr   IP address (usually as passed to gale_make_connect()). Returns: Human-readable text string describing the remote host.

void gale_daemon ( oop_source * source )

Daemonize (go into the background). Parameters: source   Liboop event source to use for signals.

int gale_data_compare ( struct gale_data a, struct gale_data b )

Compare two memory blocks, a la memcmp(). Returns: Less than zero if a < b, zero if a == b, or greater than zero if a > b.

struct gale_data gale_data_copy ( struct gale_data d )

Duplicate a region of memory. Parameters: data   Memory block to copy. Returns: A fresh copy of data.

void gale_detach ( oop_source * source )

Detach from the terminal (like galed but unlike gsub). Parameters: source   Liboop event source to use for signals.

void gale_diprintf ( int level, int indent, const char * fmt, ... )

Debugging printf. Will add indent levels of indentation. Todo: Fix this to be less gross!

void gale_do_cleanup ( void )

Call cleanup functions. Perform all cleanup functions "early". Call this if you're anticipating abrupt termination.

void gale_dprintf ( int level, const char * fmt, ... )

Debugging printf. Will only output if gale_debug > level. Todo: Fix this to be less gross!

int gale_erase_file ( const struct gale_file_state * which )

Erase a disk file. Parameters: which   State information previously collected by gale_read_file() or gale_write_file(). Returns: Nonzero if the file has not changed and was successfully erased. See also: gale_file_changed()

int gale_file_changed ( const struct gale_file_state * since )

Check to see if a disk file has changed. Parameters: since   State information previously collected by gale_read_file() or gale_write_file(). Returns: Nonzero iff the file has changed since then.

void gale_finalizer ( void * obj, void(* fun)(void *ptr,void *user), void * user )

Register a finalizer to be called when memory is garbage collected. Parameters: ptr   The memory block to watch. fun   The function to call when the memory is about to be collected. user   An extra pointer to pass to the finalizer function.

int gale_fragment_compare ( struct gale_fragment a, struct gale_fragment b )

Compare two fragments. Returns: Less than zero if a < b, zero if a == b, or greater than zero if a > b.

void gale_free ( void * ptr )

Free a block of memory. You should not need to call this except for memory obtained with gale_malloc_safe().

struct gale_time gale_get_file_time ( const struct gale_file_state * which )

Return a file's timestamp. Parameters: state   State information previously collected by gale_read_file() or gale_write_file(). Returns: The last observed modification time of the file.

void * gale_get_ptr ( struct gale_ptr * ptr )

Dereference a weak pointer. Parameters: wp   A weak pointer. Returns: A pointer to the object referenced by the weak pointer, or NULL if the object has been garbage-collected. See also: gale_make_weak()

void gale_group_add ( struct gale_group * g, struct gale_fragment f )

Add a new fragment to an existing group. Parameters: group   Pointer to the group to expand. frag   Fragment to add to the group. See also: gale_group_replace()

void gale_group_append ( struct gale_group * g, struct gale_group ga )

Concatenate two groups. Parameters: a   Pointer to the group to incorporate the other group. b   Group containing fragments to add to the other group.

int gale_group_compare ( struct gale_group a, struct gale_group b )

Compare two groups. Returns: Less than zero if a < b, zero if a == b, or greater than zero if a > b.

struct gale_fragment gale_group_first ( struct gale_group )

Return the first fragment in the specified group. (LISP 'car'.)

int gale_group_lookup ( struct gale_group group, struct gale_text name, enum gale_fragment_type type, struct gale_fragment * frag )

Find a fragment in a group by name. Parameters: group   The group to search. name   The name of the fragment to find. type   The type of the fragment to find. frag   Pointer to an uninitialized fragment. Returns: Nonzero if the fragment was found (and stored in frag).

int gale_group_remove ( struct gale_group * g, struct gale_text name, enum gale_fragment_type type )

Remove a fragment from a group. Parameters: group   Pointer to the group to be altered. name   Name of the fragment to remove. type   Type of fragment to remove. Returns: Nonzero if any fragments matched the name (and were removed).

void gale_group_replace ( struct gale_group * g, struct gale_fragment f )

Add a fragment to an existing group, replacing any others with the same name. Parameters: group   Pointer to the group to be altered. frag   Fragment to add to the group. See also: gale_group_add()

struct gale_group gale_group_rest ( struct gale_group )

Return the group consisting of all the fragments except the first. (LISP 'cdr'.)

void gale_kill ( struct gale_text class, int do_kill )

There can be only one. If do_kill is nonzero, look for other processes of the same type with the same class and kill them. In any case, register ourselves (with temp files in ~/.gale) so we can be killed when our time has come. Parameters: class   The "group" to join. Usually the terminal name. do_kill   Nonzero to kill all other processes in this group.

struct gale_connect * gale_make_connect ( oop_source * src, struct gale_text serv, int avoid_local_port, gale_connect_call * call, void * user )

Start attempting to establish a TCP connection. This function accepts a list of hostnames in serv and starts attempting to connect to all of them. The connection attempts will proceed in the background after the function returns (scheduled by liboop); the function call will be invoked when one of them succeeds or all of them fail. If the port is not specified with the serv string, the default Gale port will be used. Parameters: src   Liboop event source to use for connection. serv   Comma-separated list of one or more hostnames. avoid_local_port   If nonzero, avoid reconnecting to ourselves. call   Callback to invoke when connected attempt completes. user   User-supplied parameter, passed to call. Returns: Connection handle for use with gale_abort_connect(). See also: gale_abort_connect()

struct gale_encoding * gale_make_encoding ( struct gale_text name )

Initialize a character encoding translator. We use the iconv library, so enc can be any encoding supported by iconv ("UTF-8", "ISO-8859-1", "BIG5", etc). Normally, you don't create gale_encoding objects yourself, but use the ones in gale_global (see globals.h). See also: gale_text_from(), gale_text_to()

struct gale_map * gale_make_map ( int weak )

Create a key-value lookup table. Parameters: weak   If nonzero, create a 'weak map' using weak pointers. Objects in a weak map will not be kept alive by the map alone. If they are garbage collected, they will be removed from the map. Returns: The new, empty map. See also: gale_map_add(), gale_map_find(), gale_map_walk()

struct gale_ptr * gale_make_ptr ( void * ptr )

Create a normal pointer that looks like a weak pointer. This is useful to allow code which can operate on weak pointers or normal pointers. Parameters: ptr   An ordinary pointer to the object. Returns: A pointer to the object that looks like a weak pointer. See also: gale_make_weak(), gale_get_ptr()

struct gale_report * gale_make_report ( struct gale_report * outer )

Create a new report container. This report container is used to create a logically grouped "subreport" of another container. The outermost report container is defined in global.h. Parameters: outer   The parent report container. Returns: The new report container.

struct gale_ptr * gale_make_weak ( void * ptr )

Create a weak pointer. A 'weak pointer' doesn't prevent the object it points to from being garbage-collected. The weak pointer is set to NULL when the object it points to goes away. Parameters: ptr   The object to create a weak pointer to. Returns: A weak pointer to the object. See also: gale_get_ptr()

void * gale_malloc ( size_t len )

Allocate memory. See also: gale_create(), gale_create_array()

void gale_map_add ( struct gale_map * wt, struct gale_data key, void * data )

Add a key-value pair to a map. Parameters: map   The map to add to. key   The key to use. If another entry exists with the same key, it will be replaced by this entry. data   The data value to add. If data is NULL, any entry with this key will be removed from the map.

void * gale_map_find ( const struct gale_map * wt, struct gale_data key )

Find an entry by its key. Parameters: map   The map to search. key   The key to look for. Returns: The data associated with that key, or NULL if none was found.

int gale_map_walk ( const struct gale_map * wt, const struct gale_data * after, struct gale_data * key, void ** data )

Traverse a map in order. This function finds the first key/data entry where key > *after. If after is NULL, it finds the first entry in the map. This example counts the number of keys in a map: struct gale_map *map = ...; struct gale_data key = null_data; int count = 0; while (gale_map_walk(map,&key,&key,NULL)) ++count; Parameters: map   The map to traverse. after   The key to search for. key   Pointer to a variable to return the entry's key in. data   Pointer to a variable to return the entry's data in. Returns: Nonzero if an entry was found, zero otherwise.

void gale_on_error ( oop_source * oop, gale_call_error * func, void * user )

Set a different error handler. The function func will be called when an error is reported. Parameters: oop   The liboop source used for dispatch. func   The function to call when there's an error. user   The user-defined parameter to pass the function.

void gale_print ( FILE * fp, int attr, struct gale_text str )

Safely output a string to the console. Parameters: fp   Usually stdout or stderr. attr   Flags to use (any combination of gale_print_flags). str   The string to output.

void gale_print_line ( FILE * fp, int attr, struct gale_text )

Write a string to the console and advance to a new line. See also: gale_print()

struct gale_data gale_read_file ( struct gale_text name, int size_limit, int do_paranoia, struct gale_file_state ** state )

Read data from a disk file. Parameters: name   Filename to read. size_limit   Maximum size to read, or 0 for no limit. do_paranoia   If nonzero, will refuse to read linked files. state   If not NULL, will store state information about the file. Returns: As much data as we could suck up. See also: gale_read_from(), gale_write_file()

struct gale_data gale_read_from ( int fd, int size_limit )

Read data from a file descriptor. Parameters: fd   UNIX file descriptor to read from. size_limit   Maximum size to read, or 0 for no limit. Returns: As much data as we could suck up. See also: gale_write_to(), gale_read_file()

struct gale_text gale_read_line ( FILE * fp )

Read a line of text from a file descriptor, using readline if appropriate. Parameters: fp   File to read from (often stdin). Returns: A line of text, including the newline; or null_text at EOF.

void * gale_realloc ( void * s, size_t len )

Resize a block of memory. Parameters: mem   The original block of memory. len   The new size. Returns: The new location of the memory. See also: gale_resize_array()

void gale_report_add ( struct gale_report * rep, gale_report_call * func, void * data )

Add a report handler to a report container. Parameters: outer   The report container. func   The report generator function. user   The user-defined parameter to pass to the generator. See also: gale_report_remove()

struct gale_text gale_report_call ( void * user )

Function type for a report generator. Report generators are used to provide dumps of the internal state of the system for debugging purposes. Parameters: user   A user-defined parameter. Returns: An internal state dump.

void gale_report_remove ( struct gale_report * rep, gale_report_call * func, void * data )

Remove a report handler from a report container. Parameters: outer   The report container. func   The report generator function. user   The user-defined parameter specified to pass to the generator. See also: gale_report_add()

struct gale_text gale_report_run ( struct gale_report * rep )

Generate a report from all the report generators registered with a given report container. This is usually called automatically by SIGUSR2 and used to write a "report" file in ~/.gale. Parameters: outer   The report container. Returns: The full report text.

void gale_restart ( void )

Restart the running program. Re-exec() this program with the same argc and argv it was originally started with. This function is called automatically on SIGUSR1.

void gale_set_file_time ( struct gale_file_state * which, struct gale_time )

Set a file's timestamp. Parameters: state   State information previously collected by gale_read_file() or gale_write_file(). time   Updated timestamp.

void gale_text_accumulate ( struct gale_text_accumulator * accum, struct gale_text )

Append text to an accumulator. Parameters: accum   Accumulator to append to. text   Text to append to the accumulator.

int gale_text_accumulator_empty ( const struct gale_text_accumulator * accum )

Return nonzero if an accumulator contains any text. Parameters: accum   Accumulator to test. Returns: Nonzero if the accumulator has any text in it.

struct gale_data gale_text_as_data ( struct gale_text )

View the contexts of a text string as opaque binary data. This is typically used with gale_map structures. See also: gale_text_from_data()

struct gale_text gale_text_collect ( const struct gale_text_accumulator * accum )

Return the text collected in an accumulator. Parameters: accum   Accumulator to collect text from. Returns: All the text added to the accumulator.

int gale_text_compare ( struct gale_text a, struct gale_text b )

Compare two strings, a la strcmp(). Returns: Less than zero if a < b, zero if a == b, or greater than zero if a > b.

struct gale_text gale_text_concat ( int count, ... )

Concatenate text strings. The first argument count is the number of strings passed. Parameters: count   The number of strings to concatenate. Returns: The concatenated string. See also: gale_text_concat_array() struct gale_text stuff = G_("hi hi"); struct gale_text foobar = gale_text_concat(3,G_("foo ["),stuff,G_("] bar")); assert(0 == gale_text_compare(foobar,G_("foo [hi hi] bar")));

struct gale_text gale_text_concat_array ( int count, struct gale_text * array )

Concatenate an array of text strings. Parameters: count   The number of members in array. array   The strings to concatenate, in order. Returns: The concatenated string. See also: gale_text_concat()

struct gale_text gale_text_from ( struct gale_encoding * e, const char * p, int l )

Convert some character encoding into a Unicode string. Parameters: enc   The character encoding to use. str   The string to convert. len   The length of the string, or -1 if NUL-terminated. Returns: The string in Unicode format. See also: gale_make_encoding(), gale_text_to()

struct gale_text gale_text_from_data ( struct gale_data )

Convert opaque binary data back into a text string. See also: gale_text_as_data()

struct gale_text gale_text_from_number ( int n, int base, int pad )

Create a text representation of a number. Parameters: n   The number to format. base   The numeric base to use (0 < base <= 36). pad   The minimum field width. Zeroes will be added if necessary. Returns: The formatted representation of this number. See also: gale_text_to_number()

struct gale_text gale_text_left ( struct gale_text, int len )

Extract the leftmost substring of len characters. If len is larger than the length of the string, the entire string is returned. If len is negative, all but the rightmost -len characters are returned. If -len is larger than the length of the string, the empty string is returned. Parameters: text   The string to extract from. len   The number of characters to extract. Returns: The leftmost len characters from text.

struct gale_text gale_text_replace ( struct gale_text original, struct gale_text find, struct gale_text replace )

Replace one substring with another, everywhere it appears. Parameters: original   The original string to process. find   The string to search for in original. replace   The string to replace occurrences of find with. Returns: The value of original with replace substituted for find.

struct gale_text gale_text_right ( struct gale_text, int len )

Extract the rightmost substring of len characters. If len is larger than the length of the string, the entire string is returned. If len is negative, all but the leftmost -len characters are returned. If -len is larger than the length of the string, the empty string is returned. Parameters: text   The string to extract from. len   The number of characters to extract. Returns: The rightmost len characters from text.

char * gale_text_to ( struct gale_encoding * e, struct gale_text t )

Convert a Unicode string to some character encoding. Parameters: enc   The character encoding to use. str   The Unicode string to convert. Returns: The encoded, NUL-terminated string. See also: gale_make_encoding(), gale_text_from()

int gale_text_to_number ( struct gale_text text )

Parse a number. Parameters: text   The string to parse. Returns: The number in text, or zero if unsuccessful. See also: gale_text_from_number()

int gale_text_token ( struct gale_text string, wch sep, struct gale_text * token )

Divide a string into tokens using the separator character 'sep'. Set token to null_text initially, then call gale_text_token(str,sep,&token) repeatedly. The function will return a nonzero value as long as there is an additional token, and set token to the contents of that token. A string with N occurrences of the separator character contains 1+N tokens. This example will output 'foo', 'bar', and 'bat': struct gale_text str = G_("foo bar bat"),token = null_text; while (gale_text_token(str,' ',&token)) gale_print_line(stdout,0,token); Parameters: string   The string to tokenize. sep   The separator character to use. token   Pointer to the variable to receive the next token. Returns: Nonzero if a token was returned, or zero if there are no more.

int gale_text_width ( struct gale_text str )

Measure the width of a string, counting doublewidth CJK glyphs. Parameters: str   The string to measure. Returns: The number of character positions occupied by the string.

struct gale_time gale_time_add ( struct gale_time one, struct gale_time two )

Add two time values. Returns: A time value representing a + b.

int gale_time_compare ( struct gale_time one, struct gale_time two )

Compare two time values. Returns: Less than zero if a < b, zero if a == b, or greater than zero if a > b.

struct gale_time gale_time_diff ( struct gale_time one, struct gale_time two )

Subtract two time values. Returns: A relative time value representing a - b.

struct gale_text gale_time_format ( struct gale_time time )

Format a time value as text. Parameters: time   Time to print. Returns: Readable text representation of time.

void gale_time_from ( struct gale_time * time, const struct timeval * tv )

Convert a Unix timeval structure to a time value. Parameters: time   An uninitialized time value to write. tv   The timeval structure to convert.

void gale_time_to ( struct timeval * tv, struct gale_time time )

Convert a time value to the Unix timeval structure. Parameters: tv   An uninitialized timeval structure to write. time   The time value to convert.

void gale_watch_tty ( oop_source * source, int fd )

Deathpolling. Watch the file descriptor fd (which should be a terminal). If !isatty(fd) ever fails, raise(SIGHUP). Parameters: oop   The liboop event source to use for polling. fd   The file descriptor to watch (usually 1).

int gale_write_file ( struct gale_text name, struct gale_data data, int is_private, struct gale_file_state ** state )

Write data to a disk file. Parameters: name   Filename to write. data   Data to write to the file. is_private   If nonzero, turn off public read access. state   If not NULL, will store state information about the file. Returns: Nonzero iff all the data was successfully written. See also: gale_write_to(), gale_read_file()

int gale_write_to ( int fd, struct gale_data data )

Write data to a file descriptor. Parameters: fd   UNIX file descriptor to write to. data   Data to write. Returns: Nonzero iff all the data was successfully written. See also: gale_read_from(), gale_write_file()

void make_dir ( struct gale_text path, int mode )

Create a directory. Parameters: path   Name of directory to create. mode   Permissions to use (usually 0777)

struct gale_text sub_dir ( struct gale_text path, struct gale_text sub )

Find a subdirectory. Look for subdirectory sub of parent directory path. Return null if it doesn't already exist. Parameters: path   Parent directory to search. sub   Subdirectory to find. Returns: The full name of the subdirectory.

struct gale_text submk_dir ( struct gale_text path, struct gale_text sub, int mode )

Find a subdirectory. Look for subdirectory sub of parent directory path, and create the subdirectory if it does not already exist. Parameters: path   Parent directory to search. sub   Subdirectory to find or create. Returns: The full name of the subdirectory.

struct gale_text up_dir ( struct gale_text path )

Return the parent directory. Parameters: path   Name of a directory or file. Returns: The parent directory of path.

---