Standard utility functions

Replacements for common libc utility functions.

Since metric library functions need to be async signal safe most standard libc functions can not be used. In addition, even basic syscalls (such as read and write) cannot be used without risking corruption of some other metrics that the enclosing profiler might be tracking (for example, bytes read or bytes written). The following functions can be safely called inside signal handlers and accommodates I/O being done by the metric plugin without corrupting I/O metrics that are tracked by the enclosing profiler.

struct timespec allinea_get_current_time(void)

Gets the current time using the same clock as the enclosing profiler (async-signal-safe).

A replacement for clock_gettime that uses the enclosing profiler-preferred system clock (for example, CLOCK_MONOTONIC).

Returns

The current time.

Examples

See custom1.c.

const char * allinea_get_custom_data (metric_id_t_t metricId)

Returns the customData attribute of the source element from the metric definition defined in the xml file. See metric_id_t_t.

Parameters

Parameter	Description
metricId	The metric id.

Returns

The custom data for the given metric id. A zero length C string if not available.

void allinea_safe_fprintf(int fd, const char * format,...)

An async-signal-safe version of fprintf.

void allinea_safe_fprintf ( int          fd,
                            const char * format,
                                         ...
                          )

Parameters

Parameter	Description
fd	The file descriptor to write to.
format	The format string.
...	Zero or more values to be substituted into the format string in the same manner as printf.

int allinea_safe_open(const char * file, int oflags,...)

Opens the given file for reading or writing (async-signal-safe).

int allinea_safe_open ( const char * file,
                        int          oflags,
                                     ...
                      )

A replacement for open. When used in conjunction with allinea_safe_read() and allinea_safe_write(), the bytes read or bytes written is not included in the I/O accounting of the enclosing profiler.

Parameters

Parameter	Description
file	The name of the file to open (might be an absolute or a relative path).
oflags	Flags specifying how the file must be opened. Accepts all the flags that can be given to the libc open function, such as O_RDONLY, O_WRONLY, or O_RDWR.

Returns

The file descriptor of the open file; -1 on failure and errno set.

Examples

See custom1.c.

void allinea_safe_printf(const char * format,...)

An async-signal-safe replacement for printf.

void allinea_safe_printf ( const char * format,
                                        ...
                         )

Parameters

Parameter	Description
format	The format string.
...	Zero or more values to be substituted into the format string in the same manner as printf.

ssize_t allinea_safe_read(int fd, void * buf, size_t count)

Reads up to count bytes from buf to fd (async-signal-safe).

ssize_t allinea_safe_read ( int     fd,
                            void *  buf,
                            size_t  count
                          )

A replacement for read. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes are excluded from the enclosing profiler’s I/O accounting.

Parameters

Parameter	Description
fd	The file descriptor to read from.
buf	The buffer to read to.
count	The maximum number of bytes to read.

Returns

The number of bytes actually read; -1 on failure and errno set.

ssize_t allinea_safe_read_all(int fd, void * buf, size_t count)

Reads the entire contents of fd into buf (async-signal-safe).

ssize_t allinea_safe_read_all ( int     fd,
                                void *  buf,
                                size_t  count
                              )

When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes are excluded from the enclosing profiler’s I/O accounting.

Parameters

Parameter	Description
fd	The file descriptor to read from.
buf	Buffer in which to copy the contents.
count	Size of the buffer. At most, this many bytes are written to buf.

Returns

If successful, shows the number of bytes read, otherwise -1 and errno is set.

ssize_t allinea_safe_read_all_with_alloc(int fd, void * buf, size_t * count)

Reads the entire contents of fd into buf (async-signal-safe).

ssize_t allinea_safe_read_all_with_alloc ( int        fd,
                                           void   **  buf,
                                           size_t *   count
                                         )

When used in conjunction with allinea_safe_open() and allinea_safe_close(), the read bytes are excluded from the enclosing profiler’s I/O accounting.

When this is no longer required, use allinea_safe_free() to allocate sufficient space for the file contents and add a terminating NULL.

Parameters

Parameter	Description
fd	The file descriptor to read from.
buf	The pointer to when the buffer pointer must be stored.
count	Size of the buffer allocated.

Returns

If successful, shows the the number of bytes read, otherwise -1 and errno is set.

ssize_t allinea_safe_read_line(int fd, void * buf, size_t count)

Reads a line from fd into buf (async-signal-safe).

ssize_t allinea_safe_read_line ( int    fd,
                                 void *  buf,
                                 size_t  count
                               )

The final newline \\n is removed and a final \\0 added. When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes are excluded from the enclosing profiler’s I/O accounting.

Lines longer than count are truncated.

Parameters

Parameter	Description
fd	The file descriptor to read from.
buf	Buffer in which to copy the contents.
count	Size of the buffer. At most, this many bytes are written to buf.

Returns

If successful, shows the number of bytes read, otherwise -1 and errno is set.

Examples

See custom1.c.

void allinea_safe_vfprintf(int fd, const char * format, va_list ap)

An async-signal-safe version of vfprintf.

void allinea_safe_vfprintf ( int           fd,
                             const char *   format,
                             va_list        ap
                           )

Parameters

Parameter	Description
fd	The file descriptor to write to.
format	The format string.
ap	A list of arguments for format.

ssize_t allinea_safe_write(int fd, const void * buf, size_t count)

Writes up to count bytes from buf to fd (async-signal-safe).

ssize_t allinea_safe_write ( int          fd,
                             const void *  buf,
                             size_t        count
                           )

A replacement for write When used in conjunction with allinea_safe_open() and allinea_safe_close(), the written bytes are excluded from the I/O accounting of the enclosing profiler.

Parameters

Parameter	Description
fd	The file descriptor to write to.
buf	The buffer to write from.
count	The number of bytes to write.

Returns

The number of bytes actually written; -1 on failure and errno set.