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.

			ntdisp reference manual
Top \| Description