B2 Full Descriptions of Miscellaneous Functions

Fills string with current local date

Synopsis

C

#include "cctk.h"
#include "cctk_Misc.h.h"

int retval = Util_CurrentDate (int len, char *now);

Parameters

len length of the user-supplied string buffer
now user-supplied string buffer to write the date stamp to

Result

retval length of the string returned in now, or 0 if the string was truncated

See Also

Util_CurrentTime [B17] Fills string with current local time
Util_CurrentDateTime [B15] Returns the current datetime in a machine-processable format as defined in ISO 8601 chapter 5.4.

Returns the current datetime in a machine-processable format as defined in ISO 8601 chapter 5.4.

Synopsis

C

#include "cctk.h"
#include "cctk_Misc.h.h"

char *current_datetime = Util_CurrentDateTime ();

Result

current_datetime Pointer to an allocated formatted string containing the current datetime stamp. The pointer should be freed by the caller.

Discussion

The formatted string returned contains the current datetime in a machine-processable format as defined in ISO 8601 chapter 5.4: "YYYY-MM-DDThh:mm:ss+hh:mm”

See Also

Util_CurrentDate [B14] Fills string with current local date
Util_CurrentTime [B17] Fills string with current local time

Fills string with current local time

Synopsis

C

#include "cctk.h"
#include "cctk_Misc.h.h"

int retval = Util_CurrentTime (int len, char *now);

Parameters

len length of the user-supplied string buffer
now user-supplied string buffer to write the time stamp to

Result

retval length of the string returned in now, or 0 if the string was truncated

See Also

Util_CurrentDate [B14] Fills string with current local date
Util_CurrentDateTime [B15] Returns the current datetime in a machine-processable format as defined in ISO 8601 chapter 5.4.

Safely format data into a caller-supplied buffer.

Synopsis

C

#include "util_String.h"
int count = Util_snprintf(char* buffer, size_t size, const char* format, ...)

Result

result_len The number of characters (not including the trailing NUL) that would have been stored in the destination string if size had been infinite.

Parameters

buffer A non-NULL pointer to the (caller-provided) buffer.
size The size of the buffer pointed to by buffer.
format A (non-NULL pointer to a) C-style NUL-terminated string describing how to format any further arguments
... Zero or more further arguments, with types as specified by the format argument.

Discussion

C99 defines, and many systems provide, a C library function snprintf(), which safely formats data into a caller-supplied buffer. However, a few systems don’t provide this,¹ so Cactus provides its own version, Util_snprintf().²

The interpretation of format is the same as that of printf(). See the printf() documentation on your favorite computer system (notably, on any Unix system, type “man printf”) for lots and lots of details.

Util_snprintf() stores at most size characters in the destination buffer; the last character it stores is always the terminating NUL character. If result_len >= size then the destination string was truncated to fit into the destination buffer.

See Also

Util_vsnprintf [B24] Similar function which takes a <stdarg.h> variable argument list.
snprintf() Standard C library function which this function tries to clone.
sprintf() Unsafe and dangerous C library function similar to snprintf(), which doesn’t check the buffer length.

Errors

< 0 Some sort of error occured. It’s indeterminate what (if anything) has been stored in the destination buffer.

Examples

C

#include "util_String.h"

/* some values to be formatted */
char   c = ’@’;
int    i = 42;
double d = 3.14159265358979323846;
const char s[] = "this is a string to format";

int len;
#define N_BUFFER 100
char buffer[N_BUFFER];

/* safely format the values into the buffer */
Util_snprintf(buffer, N_BUFFER,
              "values are c=’%c’ i=%d d=%g s=\"%s\"",
              c, i, d, s);

/*
* same as above example, but now explicitly check for the output
* being truncated due to the buffer being too small
*/
const int len = Util_snprintf(buffer, N_BUFFER,
                              "values are c=’%c’ i=%d d=%g s=\"%s\"",
                              c, i, d, s);
if (len >= N_BUFFER)
        {
        /*
         * output was truncated (i.e. buffer was too small)
         * ( buffer  probably doesn’t have all the information we wanted
         * but the code is still "safe", in the sense that  buffer  is
         * still NUL-terminated, and no buffer-overflow has occured)
         */
        }

Safely format data into a caller-supplied buffer.

Synopsis

C

#include "util_String.h"
int count = Util_vsnprintf(char* buffer, size_t size, const char* format,
va_list arg)

Discussion

This function is identical to Util_snprintf, except that it takes its data arguements in the form of a va_list “cookie” (as defined by <stdarg.h>, which is already included by "util_String.h"), instead of in the from of a variable length argument list.

See Also

Util_snprintf [B19] Similar function which takes a variable length argument list.
vsnprintf() Standard C library function which this function tries to clone.
vsprintf() Unsafe and dangerous C library function similar to vsnprintf(), which doesn’t check the buffer length.
<stdarg.h> System header file which defines the va_list “cookie” type and various macros to manipulate it. On most Unix systems the man page for this header file this also includes a mini-tutorial on how to use va_list objects.

Chapter B2Full Descriptions of Miscellaneous Functions

Util_CurrentDate

Util_CurrentDateTime

Util_CurrentTime

Util_snprintf

Util_vsnprintf

Chapter B2
Full Descriptions of Miscellaneous Functions