glib provides many useful functions and definitions available for use when creating GDK and GTK applications. I will list them all here with a brief explanation. Many are duplicates of standard libc functions so I won't go into detail on those. This is mostly to be used as a reference, so you know what is available for use.
Definitions for the extremes of many of the standard types are:
G_MINFLOAT
G_MAXFLOAT
G_MINDOUBLE
G_MAXDOUBLE
G_MINSHORT
G_MAXSHORT
G_MININT
G_MAXINT
G_MINLONG
G_MAXLONG
Also, the following typedefs. The ones left unspecified are dynamically set depending on the architecture. Remember to avoid counting on the size of a pointer if you want to be portable! Eg, a pointer on an Alpha is 8 bytes, but 4 on Intel.
char gchar;
short gshort;
long glong;
int gint;
char gboolean;
unsigned char guchar;
unsigned short gushort;
unsigned long gulong;
unsigned int guint;
float gfloat;
double gdouble;
long double gldouble;
void* gpointer;
gint8
guint8
gint16
guint16
gint32
guint32
The following functions are used to create, manage, and destroy doubly linked lists. I assume you know what linked lists are, as it is beyond the scope of this document to explain them. Of course, it's not required that you know these for general use of GTK, but they are nice to know.
GList* g_list_alloc (void);
void g_list_free (GList *list);
void g_list_free_1 (GList *list);
GList* g_list_append (GList *list,
gpointer data);
GList* g_list_prepend (GList *list,
gpointer data);
GList* g_list_insert (GList *list,
gpointer data,
gint position);
GList* g_list_remove (GList *list,
gpointer data);
GList* g_list_remove_link (GList *list,
GList *link);
GList* g_list_reverse (GList *list);
GList* g_list_nth (GList *list,
gint n);
GList* g_list_find (GList *list,
gpointer data);
GList* g_list_last (GList *list);
GList* g_list_first (GList *list);
gint g_list_length (GList *list);
void g_list_foreach (GList *list,
GFunc func,
gpointer user_data);
Many of the above functions for singly linked lists are identical to the above. Here is a complete list:
GSList* g_slist_alloc (void);
void g_slist_free (GSList *list);
void g_slist_free_1 (GSList *list);
GSList* g_slist_append (GSList *list,
gpointer data);
GSList* g_slist_prepend (GSList *list,
gpointer data);
GSList* g_slist_insert (GSList *list,
gpointer data,
gint position);
GSList* g_slist_remove (GSList *list,
gpointer data);
GSList* g_slist_remove_link (GSList *list,
GSList *link);
GSList* g_slist_reverse (GSList *list);
GSList* g_slist_nth (GSList *list,
gint n);
GSList* g_slist_find (GSList *list,
gpointer data);
GSList* g_slist_last (GSList *list);
gint g_slist_length (GSList *list);
void g_slist_foreach (GSList *list,
GFunc func,
gpointer user_data);
gpointer g_malloc (gulong size);
This is a replacement for malloc(). You do not need to check the return vaule as it is done for you in this function.
gpointer g_malloc0 (gulong size);
Same as above, but zeroes the memory before returning a pointer to it.
gpointer g_realloc (gpointer mem,
gulong size);
Relocates "size" bytes of memory starting at "mem". Obviously, the memory should have been previously allocated.
void g_free (gpointer mem);
Frees memory. Easy one.
void g_mem_profile (void);
Dumps a profile of used memory, but requries that you add #define MEM_PROFILE to the top of glib/gmem.c and re-make and make install.
void g_mem_check (gpointer mem);
Checks that a memory location is valid. Requires you add #define MEM_CHECK to the top of gmem.c and re-make and make install.
Timer functions..
GTimer* g_timer_new (void);
void g_timer_destroy (GTimer *timer);
void g_timer_start (GTimer *timer);
void g_timer_stop (GTimer *timer);
void g_timer_reset (GTimer *timer);
gdouble g_timer_elapsed (GTimer *timer,
gulong *microseconds);
A whole mess of string handling functions. They all look very interesting, and probably better for many purposes than the standard C string functions, but require documentation.
GString* g_string_new (gchar *init);
void g_string_free (GString *string,
gint free_segment);
GString* g_string_assign (GString *lval,
gchar *rval);
GString* g_string_truncate (GString *string,
gint len);
GString* g_string_append (GString *string,
gchar *val);
GString* g_string_append_c (GString *string,
gchar c);
GString* g_string_prepend (GString *string,
gchar *val);
GString* g_string_prepend_c (GString *string,
gchar c);
void g_string_sprintf (GString *string,
gchar *fmt,
...);
void g_string_sprintfa (GString *string,
gchar *fmt,
...);
gchar* g_strdup (const gchar *str);
Replacement strdup function. Copies the original strings contents to newly allocated memory, and returns a pointer to it.
gchar* g_strerror (gint errnum);
I recommend using this for all error messages. It's much nicer, and more portable than perror() or others. The output is usually of the form:
program name:function that failed:file or further description:strerror
Here's an example of one such call used in our hello_world program:
g_print("hello_world:open:%s:%s\n", filename, g_strerror(errno));
void g_error (gchar *format, ...);
Prints an error message. The format is just like printf, but it prepends "** ERROR **: " to your message, and exits the program. Use only for fatal errors.
void g_warning (gchar *format, ...);
Same as above, but prepends "** WARNING **: ", and does not exit the program.
void g_message (gchar *format, ...);
Prints "message: " prepended to the string you pass in.
void g_print (gchar *format, ...);
Replacement for printf().
And our last function:
gchar* g_strsignal (gint signum);
Prints out the name of the Unix system signal given the signal number. Useful in generic signal handling functions.
All of the above are more or less just stolen from glib.h. If anyone cares to document any function, just send me an email!