Utilities

Utilities — Assorted macros and functions

Synopsis

#define             NTD_SYSTEM_ERROR
#define             ntd_log_pileup                      (err)
#define             ntd_return_on_pileup                (err)
#define             ntd_return_val_on_pileup            (err,
                                                         val)
#define             ntd_empty                           (string)
enum                NtdSystemError;
GQuark              ntd_system_error_quark              (void);
NtdSystemError      ntd_system_get_error                (void);
gchar *             ntd_system_get_error_message        (NtdSystemError error_code);
gboolean            ntd_system_set_error                (GError **error,
                                                         const gchar *format,
                                                         ...);
gboolean            ntd_system_set_errorv               (GError **error,
                                                         const gchar *format,
                                                         va_list args);
void                ntd_system_set_error_with_code      (GError **error,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         ...);
void                ntd_system_set_errorv_with_code     (GError **error,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         va_list args);
void                ntd_system_clear_error              (void);
void                ntd_set_verbose_mode                (gboolean new_status);
gchar *             ntd_escape                          (gconstpointer buffer,
                                                         gsize nbytes);
gulong              ntd_checksum                        (gconstpointer data,
                                                         gsize nbytes);
gchar *             ntd_find_file                       (const gchar *file,
                                                         ...);
void                ntd_string_free                     (GString *string,
                                                         gpointer *p_buffer,
                                                         gsize *p_len);
void                ntd_free_and_nullify                (gpointer *mem);
gchar *             ntd_uuencode                        (gconstpointer data,
                                                         gsize nbytes);
gboolean            ntd_uudecode                        (const gchar *encoded,
                                                         gpointer *p_data,
                                                         gsize *p_nbytes);

Description

Collection of macros and functions that do not fit inside any other topic.

Details

NTD_SYSTEM_ERROR

#define NTD_SYSTEM_ERROR        ntd_system_error_quark()

ntd_log_pileup()

#define             ntd_log_pileup(err)

ntd_return_on_pileup()

#define             ntd_return_on_pileup(err)

ntd_return_val_on_pileup()

#define             ntd_return_val_on_pileup(err,val)

ntd_empty()

#define             ntd_empty(string)

Checks wheter string is empty, that is if string is NULL or if its first char is '\0'.

string :

char pointer

Returns :

TRUE is string is NULL or if string[0] is '\0', FALSE otherwise.

enum NtdSystemError

typedef enum {
    /* NtdSystemError specific */
    NTD_SYSTEM_ERROR_NONE,
    NTD_SYSTEM_ERROR_FAILED,

    /* Derived from errno values on POSIX.1 (2001 edition) */
    NTD_SYSTEM_ERROR_2BIG,
    NTD_SYSTEM_ERROR_ACCES,
    NTD_SYSTEM_ERROR_ADDRINUSE,
    NTD_SYSTEM_ERROR_ADDRNOTAVAIL,
    NTD_SYSTEM_ERROR_AFNOSUPPORT,
    NTD_SYSTEM_ERROR_AGAIN,
    NTD_SYSTEM_ERROR_ALREADY,
    NTD_SYSTEM_ERROR_BADF,
    NTD_SYSTEM_ERROR_BADMSG,
    NTD_SYSTEM_ERROR_BUSY,
    NTD_SYSTEM_ERROR_CANCELED,
    NTD_SYSTEM_ERROR_CHILD,
    NTD_SYSTEM_ERROR_CONNABORTED,
    NTD_SYSTEM_ERROR_CONNREFUSED,
    NTD_SYSTEM_ERROR_CONNRESET,
    NTD_SYSTEM_ERROR_DEADLK,
    NTD_SYSTEM_ERROR_DESTADDRREQ,
    NTD_SYSTEM_ERROR_DOM,
    NTD_SYSTEM_ERROR_EXIST,
    NTD_SYSTEM_ERROR_FAULT,
    NTD_SYSTEM_ERROR_FBIG,
    NTD_SYSTEM_ERROR_HOSTUNREACH,
    NTD_SYSTEM_ERROR_IDRM,
    NTD_SYSTEM_ERROR_ILSEQ,
    NTD_SYSTEM_ERROR_INPROGRESS,
    NTD_SYSTEM_ERROR_INTR,
    NTD_SYSTEM_ERROR_INVAL,
    NTD_SYSTEM_ERROR_IO,
    NTD_SYSTEM_ERROR_ISCONN,
    NTD_SYSTEM_ERROR_ISDIR,
    NTD_SYSTEM_ERROR_LOOP,
    NTD_SYSTEM_ERROR_MFILE,
    NTD_SYSTEM_ERROR_MLINK,
    NTD_SYSTEM_ERROR_MSGSIZE,
    NTD_SYSTEM_ERROR_NAMETOOLONG,
    NTD_SYSTEM_ERROR_NETDOWN,
    NTD_SYSTEM_ERROR_NETRESET,
    NTD_SYSTEM_ERROR_NETUNREACH,
    NTD_SYSTEM_ERROR_NFILE,
    NTD_SYSTEM_ERROR_NOBUFS,
    NTD_SYSTEM_ERROR_NODATA,
    NTD_SYSTEM_ERROR_NODEV,
    NTD_SYSTEM_ERROR_NOENT,
    NTD_SYSTEM_ERROR_NOEXEC,
    NTD_SYSTEM_ERROR_NOLCK,
    NTD_SYSTEM_ERROR_NOMEM,
    NTD_SYSTEM_ERROR_NOMSG,
    NTD_SYSTEM_ERROR_NOPROTOOPT,
    NTD_SYSTEM_ERROR_NOSPC,
    NTD_SYSTEM_ERROR_NOSR,
    NTD_SYSTEM_ERROR_NOSTR,
    NTD_SYSTEM_ERROR_NOSYS,
    NTD_SYSTEM_ERROR_NOTCONN,
    NTD_SYSTEM_ERROR_NOTDIR,
    NTD_SYSTEM_ERROR_NOTEMPTY,
    NTD_SYSTEM_ERROR_NOTSOCK,
    NTD_SYSTEM_ERROR_NOTSUP,
    NTD_SYSTEM_ERROR_NOTTY,
    NTD_SYSTEM_ERROR_NXIO,
    NTD_SYSTEM_ERROR_OPNOTSUPP,
    NTD_SYSTEM_ERROR_OVERFLOW,
    NTD_SYSTEM_ERROR_PERM,
    NTD_SYSTEM_ERROR_PIPE,
    NTD_SYSTEM_ERROR_PROTO,
    NTD_SYSTEM_ERROR_PROTONOSUPPORT,
    NTD_SYSTEM_ERROR_PROTOTYPE,
    NTD_SYSTEM_ERROR_RANGE,
    NTD_SYSTEM_ERROR_ROFS,
    NTD_SYSTEM_ERROR_SPIPE,
    NTD_SYSTEM_ERROR_SRCH,
    NTD_SYSTEM_ERROR_TIME,
    NTD_SYSTEM_ERROR_TIMEDOUT,
    NTD_SYSTEM_ERROR_TXTBSY,
    NTD_SYSTEM_ERROR_XDEV
} NtdSystemError;

Abstraction of the platform dependent error codes. This implementation should be in-line with POSIX.1-2001.

NTD_SYSTEM_ERROR_NONE

No error present

NTD_SYSTEM_ERROR_FAILED

Generic failure

NTD_SYSTEM_ERROR_2BIG

Argument list too long

NTD_SYSTEM_ERROR_ACCES

Permission denied

NTD_SYSTEM_ERROR_ADDRINUSE

Address already in use

NTD_SYSTEM_ERROR_ADDRNOTAVAIL

Cannot assign requested address

NTD_SYSTEM_ERROR_AFNOSUPPORT

Address family not supported by protocol

NTD_SYSTEM_ERROR_AGAIN

Try again

NTD_SYSTEM_ERROR_ALREADY

Operation already in progress

NTD_SYSTEM_ERROR_BADF

Bad file number

NTD_SYSTEM_ERROR_BADMSG

Not a data message

NTD_SYSTEM_ERROR_BUSY

Device or resource busy

NTD_SYSTEM_ERROR_CANCELED

Operation Canceled

NTD_SYSTEM_ERROR_CHILD

No child processes

NTD_SYSTEM_ERROR_CONNABORTED

Software caused connection abort

NTD_SYSTEM_ERROR_CONNREFUSED

Connection refused

NTD_SYSTEM_ERROR_CONNRESET

Connection reset by peer

NTD_SYSTEM_ERROR_DEADLK

Resource deadlock would occur

NTD_SYSTEM_ERROR_DESTADDRREQ

Destination address required

NTD_SYSTEM_ERROR_DOM

Math argument out of domain of func

NTD_SYSTEM_ERROR_EXIST

File exists

NTD_SYSTEM_ERROR_FAULT

Bad address

NTD_SYSTEM_ERROR_FBIG

File too large

NTD_SYSTEM_ERROR_HOSTUNREACH

No route to host

NTD_SYSTEM_ERROR_IDRM

Identifier removed NTD_SYSTEM_ERROR_DEADLOCK EDEADLK

NTD_SYSTEM_ERROR_ILSEQ

Illegal byte sequence

NTD_SYSTEM_ERROR_INPROGRESS

Operation now in progress

NTD_SYSTEM_ERROR_INTR

Interrupted system call

NTD_SYSTEM_ERROR_INVAL

Invalid argument

NTD_SYSTEM_ERROR_IO

I/O error

NTD_SYSTEM_ERROR_ISCONN

Transport endpoint is already connected

NTD_SYSTEM_ERROR_ISDIR

Is a directory

NTD_SYSTEM_ERROR_LOOP

Too many symbolic links encountered

NTD_SYSTEM_ERROR_MFILE

Too many open files

NTD_SYSTEM_ERROR_MLINK

Too many links

NTD_SYSTEM_ERROR_MSGSIZE

Message too long

NTD_SYSTEM_ERROR_NAMETOOLONG

File name too long

NTD_SYSTEM_ERROR_NETDOWN

Network is down

NTD_SYSTEM_ERROR_NETRESET

Network dropped connection because of reset

NTD_SYSTEM_ERROR_NETUNREACH

Network is unreachable

NTD_SYSTEM_ERROR_NFILE

File table overflow

NTD_SYSTEM_ERROR_NOBUFS

No buffer space available

NTD_SYSTEM_ERROR_NODATA

No data available

NTD_SYSTEM_ERROR_NODEV

No such device

NTD_SYSTEM_ERROR_NOENT

No such file or directory

NTD_SYSTEM_ERROR_NOEXEC

Exec format error

NTD_SYSTEM_ERROR_NOLCK

No record locks available

NTD_SYSTEM_ERROR_NOMEM

Out of memory

NTD_SYSTEM_ERROR_NOMSG

No message of desired type

NTD_SYSTEM_ERROR_NOPROTOOPT

Protocol not available

NTD_SYSTEM_ERROR_NOSPC

No space left on device

NTD_SYSTEM_ERROR_NOSR

Out of streams resources

NTD_SYSTEM_ERROR_NOSTR

Device not a stream

NTD_SYSTEM_ERROR_NOSYS

Function not implemented

NTD_SYSTEM_ERROR_NOTCONN

Transport endpoint is not connected

NTD_SYSTEM_ERROR_NOTDIR

Not a directory

NTD_SYSTEM_ERROR_NOTEMPTY

Directory not empty

NTD_SYSTEM_ERROR_NOTSOCK

Socket operation on non-socket

NTD_SYSTEM_ERROR_NOTSUP

Operation not supported on transport endpoint

NTD_SYSTEM_ERROR_NOTTY

Not a typewriter

NTD_SYSTEM_ERROR_NXIO

No such device or address

NTD_SYSTEM_ERROR_OPNOTSUPP

Operation not supported on transport endpoint

NTD_SYSTEM_ERROR_OVERFLOW

Value too large for defined data type

NTD_SYSTEM_ERROR_PERM

Operation not permitted

NTD_SYSTEM_ERROR_PIPE

Broken pipe

NTD_SYSTEM_ERROR_PROTO

Protocol error

NTD_SYSTEM_ERROR_PROTONOSUPPORT

Protocol not supported

NTD_SYSTEM_ERROR_PROTOTYPE

Protocol wrong type for socket

NTD_SYSTEM_ERROR_RANGE

Math result not representable

NTD_SYSTEM_ERROR_ROFS

Read-only file system

NTD_SYSTEM_ERROR_SPIPE

Illegal seek

NTD_SYSTEM_ERROR_SRCH

No such process

NTD_SYSTEM_ERROR_TIME

Timer expired

NTD_SYSTEM_ERROR_TIMEDOUT

Connection timed out

NTD_SYSTEM_ERROR_TXTBSY

Text file busy

NTD_SYSTEM_ERROR_XDEV

Cross-device link

ntd_system_error_quark ()

GQuark              ntd_system_error_quark              (void);

ntd_system_get_error ()

NtdSystemError      ntd_system_get_error                (void);

Gets the current NtdSystemError error code from the system.

Returns :

the NtdSystemError of the current system error, or NTD_SYSTEM_ERROR_NONE if there are no system errors.

ntd_system_get_error_message ()

gchar *             ntd_system_get_error_message        (NtdSystemError error_code);

Gets the description of the specified system error. If the error_code has no meaning for the operating system, this function returns NULL.

error_code :

the error code to convert.

Returns :

a newly allocated string containig the error message. This string must be freed when no longer used. TODO: Implement a reentrant version.

ntd_system_set_error ()

gboolean            ntd_system_set_error                (GError **error,
                                                         const gchar *format,
                                                         ...);

Sets error to the properly system error, if there is one active. The optional format string is appended to the standard system error message. If there are no system errors, this function does nothing and return FALSE.

After the error is set, a ntd_system_clear_error() call is performed to clear the system error.

error :

a pointer to the destination GError*.

format :

printf-style format string.

... :

parameters for format string.

Returns :

TRUE if there is a system error, FALSE otherwise.

ntd_system_set_errorv ()

gboolean            ntd_system_set_errorv               (GError **error,
                                                         const gchar *format,
                                                         va_list args);

Wrapper to ntd_system_set_error() with va_list argument.

error :

a pointer to the destination GError*.

format :

printf-style format string.

args :

parameters for format string.

Returns :

TRUE if there is a system error, FALSE otherwise.

ntd_system_set_error_with_code ()

void                ntd_system_set_error_with_code      (GError **error,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         ...);

Sets error to the specified system error, exactly in the same way the ntd_system_set_error() function does.

Of course, in this case the error_code is not system dependent, so no ntd_system_clear_error() call is performed and nothing is returned.

Calling this function with NTD_SYSTEM_ERROR_NONE as the error_code it is equivalent to call g_clear_error() on error.

error :

a pointer to the destination GError*.

error_code :

the specific system error code to set.

format :

printf-style format string.

... :

parameters for format string.

ntd_system_set_errorv_with_code ()

void                ntd_system_set_errorv_with_code     (GError **error,
                                                         NtdSystemError error_code,
                                                         const gchar *format,
                                                         va_list args);

Wrapper to ntd_system_set_error_with_code() with va_list argument.

error :

a pointer to the destination GError*.

error_code :

the specific system error code to set.

format :

printf-style format string.

args :

parameters for format string.

ntd_system_clear_error ()

void                ntd_system_clear_error              (void);

Resets the system for any pending error.


ntd_set_verbose_mode ()

void                ntd_set_verbose_mode                (gboolean new_status);

Enables (if new_status is TRUE) or disables (if new_status is FALSE) the verbosity mode. In verbose mode, data sent to or received from the device is output to stdout.

new_status :

new verbosity status

ntd_escape ()

gchar *             ntd_escape                          (gconstpointer buffer,
                                                         gsize nbytes);

Generates a printable representation of the first nbytes bytes of buffer. This is done by escaping all non-printable chars.

The buffer is split on the '\0' delimiters. Every segment in the resulting list of strings is then escaped with g_strescape(). The final list is then joined with the "\\000" string (octal representation of '\0'): at the end, all non-printable characters (NUL bytes included) are properly escaped.

buffer :

a buffer

nbytes :

size of the buffer

Returns :

a newly allocated string: free with g_free() when no longer needed.

ntd_checksum ()

gulong              ntd_checksum                        (gconstpointer data,
                                                         gsize nbytes);

Sums the first nbytes bytes of data and returns the result. No checks against arithmetic overflows are performed.

data :

binary buffer

nbytes :

size (in bytes) of the data

Returns :

the computed checksum

ntd_find_file ()

gchar *             ntd_find_file                       (const gchar *file,
                                                         ...);

Searches file in the provided paths and returns the full path to the first existing match. The check is performed using g_file_test() with the G_FILE_TEST_EXISTS test.

file :

the file to search

... :

a NULL terminated list of paths where to look for file existence.

Returns :

a newly allocated string containing the path or NULL on errors. Free it with g_free() when no longer needed.

ntd_string_free ()

void                ntd_string_free                     (GString *string,
                                                         gpointer *p_buffer,
                                                         gsize *p_len);

A g_string_free() version that returns either the buffer in whatever p_buffer and its length in p_len. Both of them can be NULL, in which case the data is not returned (but it is freed anyway).

Furthermore, the case where string is NULL is handled gracefully: p_buffer and p_len are set to NULL and 0 respectively (if possible).

string :

a GString

p_buffer :

destination of the buffer or NULL

p_len :

destionation of the buffer length or NULL

ntd_free_and_nullify ()

void                ntd_free_and_nullify                (gpointer *mem);

Convenient function to free mem with g_free() and set it to NULL.

mem :

pointer to the pointer to free.

ntd_uuencode ()

gchar *             ntd_uuencode                        (gconstpointer data,
                                                         gsize nbytes);

Converts nbytes bytes from data to their uu-encoded version.

data :

original binary buffer

nbytes :

size (in bytes) of the data to convert

Returns :

the uu-encoded '\0' terminated result of the conversion or NULL on errors. Free the returned string with g_free() when no longer needed.

ntd_uudecode ()

gboolean            ntd_uudecode                        (const gchar *encoded,
                                                         gpointer *p_data,
                                                         gsize *p_nbytes);

Decodes the encoded string and returns the decoded result in p_nbytes and p_data. Either p_nbytes and p_data can be NULL, in which case the respective result will not be returned.

encoded :

'\0' terminated string of UU-encoded data

p_data :

pointer to the destination buffer to allocate

p_nbytes :

pointer to the destination size (in bytes) of the data

Returns :

TRUE on success, FALSE on errors.