# CTIME Formatting

### Overview

CTIME formatting provides a way to format timestamps using directives similar to the Unix `strftime` function. This guide explains how to use CTIME format strings with practical examples.

### Basic Concept

CTIME formatting works by replacing format directives (special character sequences starting with `%`) with their corresponding components from a date/time value. For example:

* `%Y` represents the full 4-digit year
* `%m` represents the month (zero-padded)
* `%d` represents the day of month (zero-padded)

### Common Timestamp Format Examples

#### ISO 8601 Format

```
Format:  %F %T
Example: 2025-12-23 14:30:45
```

Equivalent to: `%Y-%m-%d %H:%M:%S`

#### US Short Date Format

```
Format:  %m/%d/%y
Example: 12/23/25
```

Same as the `%D` or `%x` directive

#### Full Date and Time

```
Format:  %c
Example: Mon Dec 23 14:30:45 2025
```

Complete date and time representation

#### 12-Hour Time with AM/PM

```
Format:  %I:%M:%S %p
Example: 02:30:45 PM
```

#### 24-Hour Time Only

```
Format:  %R
Example: 14:30
```

Equivalent to: `%H:%M`

#### For 24-hour time with seconds:

```
Format:  %T
Example: 14:30:45
```

Equivalent to: `%H:%M:%S`

#### RFC 2822 Style

```
Format:  %a, %b %d %Y %H:%M:%S %z
Example: Mon, Dec 23 2025 14:30:45 -0700
```

#### Log Timestamp Format

```
Format:  %Y-%m-%d %H:%M:%S.%L
Example: 2025-12-23 14:30:45.999
```

#### Verbose Format

```
Format:  %A, %B %d, %Y at %I:%M %p
Example: Monday, December 23, 2025 at 02:30 PM
```

### Directive Reference

#### Year

| Directive | Description                   | Example |
| --------- | ----------------------------- | ------- |
| `%Y`      | Year, zero-padded (0001-9999) | 2025    |
| `%y`      | Year, last two digits         | 25      |

#### Month

| Directive  | Description               | Example  |
| ---------- | ------------------------- | -------- |
| `%m`       | Month as decimal (01-12)  | 12       |
| `%o`       | Month space-padded (1-12) | 12       |
| `%q`       | Month unpadded (1-12)     | 12       |
| `%B`       | Full month name           | December |
| `%b`, `%h` | Abbreviated month         | Dec      |

#### Day of Month

| Directive | Description             | Example |
| --------- | ----------------------- | ------- |
| `%d`      | Day zero-padded (01-31) | 23      |
| `%e`      | Day space-padded (1-31) | 23      |
| `%g`      | Day unpadded (1-31)     | 23      |

#### Weekday

| Directive | Description         | Example |
| --------- | ------------------- | ------- |
| `%A`      | Full weekday name   | Monday  |
| `%a`      | Abbreviated weekday | Mon     |

#### Hour (24-hour clock)

| Directive | Description              | Example |
| --------- | ------------------------ | ------- |
| `%H`      | Hour zero-padded (00-23) | 14      |

#### Hour (12-hour clock)

| Directive | Description              | Example |
| --------- | ------------------------ | ------- |
| `%I`      | Hour zero-padded (01-12) | 02      |
| `%l`      | Hour unpadded (0-12)     | 2       |
| `%p`      | Locale AM/PM             | PM      |
| `%P`      | Locale am/pm             | pm      |

#### Minute

| Directive | Description                | Example |
| --------- | -------------------------- | ------- |
| `%M`      | Minute zero-padded (00-59) | 30      |

#### Second

| Directive | Description                | Example |
| --------- | -------------------------- | ------- |
| `%S`      | Second zero-padded (00-59) | 45      |

#### Fractional Seconds

| Directive | Description                      | Example   |
| --------- | -------------------------------- | --------- |
| `%L`      | Millisecond (000-999)            | 500       |
| `%f`      | Microsecond (000000-999999)      | 500000    |
| `%s`      | Nanosecond (000000000-999999999) | 500000000 |

#### Timezone

| Directive | Description                       | Example   |
| --------- | --------------------------------- | --------- |
| `%Z`      | Timezone name/abbreviation        | MST       |
| `%z`      | UTC offset (±HHMM\[SS\[.ffffff]]) | -0700     |
| `%w`      | UTC offset with seconds           | -070000   |
| `%i`      | UTC offset (short form)           | -07       |
| `%j`      | UTC offset with colons            | -07:00    |
| `%k`      | UTC offset full format            | -07:00:00 |

#### Composite Formats

| Directive  | Description                | Equivalent               |
| ---------- | -------------------------- | ------------------------ |
| `%D`, `%x` | Short date (MM/DD/YY)      | %m/%d/%y                 |
| `%F`       | ISO 8601 date (YYYY-MM-DD) | %Y-%m-%d                 |
| `%T`, `%X` | ISO 8601 time (HH:MM:SS)   | %H:%M:%S                 |
| `%R`       | 24-hour time (HH:MM)       | %H:%M                    |
| `%r`       | 12-hour time with AM/PM    | HH:MM:SS am/pm           |
| `%c`       | Full date and time         | Mon Jan 02 15:04:05 2006 |

#### Special Characters

| Directive | Description              |
| --------- | ------------------------ |
| `%n`      | Newline character        |
| `%t`      | Horizontal tab character |
| `%%`      | Literal % sign           |

### Practical Usage Tips

1. **Combining Directives**: You can mix multiple directives in a single format string

   ```
   %Y-%m-%d %H:%M:%S   →   2025-12-23 14:30:45
   ```
2. **Padding Variations**: Different directives provide different padding options for the same component

   ```
   %m  →  12 (zero-padded)
   %o  →  12 (space-padded)
   %q  →  12 (unpadded)
   ```
3. **Timezone Information**: Include timezone data for complete timestamp information

   ```
   %Y-%m-%d %H:%M:%S %Z   →   2025-12-23 14:30:45 MST
   ```
4. **Readable Formats**: Use full month and weekday names for human-readable timestamps

   ```
   %A, %B %d %Y   →   Monday, December 23 2025
   ```
5. **Millisecond Precision**: Include `%L` for application logs

   ```
   %Y-%m-%d %H:%M:%S.%L   →   2025-12-23 14:30:45.500
   ```

### Example Use Cases

#### Server Log Entry

```
[%Y-%m-%d %H:%M:%S.%L] User login: admin
→ [2025-12-23 14:30:45.500] User login: admin
```

#### API Response Timestamp

```
{
  "timestamp": "%FT%T%z",
  "event": "order_placed"
}
→ "timestamp": "2025-12-23T14:30:45-0700"
```

#### Email Header Format

```
Date: %a, %d %b %Y %H:%M:%S %z
→ Date: Mon, 23 Dec 2025 14:30:45 -0700
```

#### Database Audit Log

```
%Y-%m-%d %H:%M:%S | %A | Action: UPDATE
→ 2025-12-23 14:30:45 | Monday | Action: UPDATE
```

#### User-Friendly Display

```
"Last updated: %A at %I:%M %p"
→ "Last updated: Monday at 02:30 PM"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bindplane.com/how-to-guides/data-collection-and-processing/ctime-formatting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.