---
name: "TSUuidCreate"
section: "3ts"
platform: "linux"
package: "trafficserver-dev"
version: "9.2.5+ds-0+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/TSUuidCreate"
---

# TSUuidCreate(3ts)

traffic Server UUID construction APIs

## NAME

TSUuidCreate - traffic Server UUID construction APIs

## SYNOPSIS

```
#include <ts/ts.h>
```

- ***TSUuid* TSUuidCreate(void)**

  - ***TSReturnCode* TSUuidInitialize(*TSUuid* uuid, *TSUuidVersion* v)**

  - **void TSUuidDestroy(*TSUuid* uuid)**

  - ***TSReturnCode* TSUuidCopy(*TSUuid* dest, const *TSUuid* src)**

  - **const char \*TSUuidStringGet(const *TSUuid* uuid)**

  - ***TSUuidVersion* TSUuidVersionGet(const *TSUuid* uuid)**

  - ***TSReturnCode* TSUuidStringParse(*TSUuid* uuid, const char \*uuid\_str)**

  - **const *TSUuid* TSProcessUuidGet(void)**

  - ***TSReturnCode* TSClientRequestUuidGet(*TSHttpTxn* txnp, char \*uuid\_str)**

  ## DESCRIPTION

These APIs are used to create, manage, and use UUIDs in a plugin, implementing part of *RFC 4122*. Currently, only the V4 variant of the specifications is implemented. In addition, an internal, process unique UUID is provided, which can be used to uniquely identifying the running Traffic Server process.

*TSUuidCreate()* creates a new *TSUuid* object, which is returned and can be used by the other APIs. Similarly, a read-only global process UUID is returned from the function *TSProcessUuidGet()*. You must not attempt to modify any data as returned by either of these functions.

*TSUuidInitialize()* initializes a *TSUuid* object, using the algorithm defined for the specified version. Note that only the V4 variants is currently supported. You can call *TSUuidInitialize()* repeatedly, which each generates a new UUID, but this will overwrite any existing UUID data in the object. This also implies that any strings retrieved using *TSUuidStringGet()* are also modified accordingly.

*TSUuidDestroy()* destroys (releases) an *TSUuid* object, and frees all memory associated with this object. This includes any strings as returned by e.g. *TSUuidStringGet()*.

*TSUuidCopy()* copies one *TSUuid* to another, making an exact duplicate. Note that both the source and the destination UUIDs must be created appropriately, and should not have been previously destroyed.

*TSUuidVersionGet()* returns the version number for the *TSUuid*. This will work properly for any *RFC 4122* initialized UUID object, e.g. if you parse a string with *TSUuidStringParse()* this will return the correct variant ID.

*TSUuidStringGet()* returns a pointer to the internal string representation of the *TSUuid* object. It's important to know that there is no transfer of ownership of this string. If you need a copy of it, you are responsible of doing so yourself. In particular, using a string as returned by *TSUuidStringGet()* **after** you have called *TSUuidDestroy()* on the corresponding *TSUuid* object is a serious error. The UUID object does not do any sort of reference counting on the string, and you must absolutely not free the memory as returned by this API.

*TSUuidStringParse()* can be used to convert an existing *TSUuid* string to a Traffic Server UUID object. This will only succeed if the *TSUuid* string is a proper *RFC 4122* UUID. The *TSUuid* argument passed to this function must be a properly *TSUuidCreate()* object, but it does not need to be previously initialized.

Finally, *TSClientRequestUuidGet()* can be used to extract the client request uuid from a transaction. The output buffer must be of sufficient length, minimum of **TS\_CRUUID\_STRING\_LEN** + 1 bytes. This produces the same string as the log tag %\<cruuid\> generates, and it will be NULL terminated.

## RETURN VALUES

The *TSUuid* type is an opaque pointer to an internal representation of the UUID object. Several of the functions returns a normal Traffic Server return status code, *TSReturnCode*. You should verify the success of those APIs, of course.

The *TSUuidStringGet()* function will return **NULL** if the *TSUuid* object is not properly initialized. Likewise, *TSUuidVersionGet()* would then return **TS\_UUID\_UNDEFINED**.

The *TSUuidDestroy()* function can not fail, and does not have a return value,  but you are of course responsible for providing a valid *TSUuid* object.

## EXAMPLES

```
#include <ts/ts.h>
TSUuid machine, uuid;
machine = TSProcessUuidGet();
printf("Machine UUID is %s\n", TSUuidStringGet(machine);
if (uuid = TSUuidCreate()) {
  if (TS_SUCCESS == TSUuidInitialize(uuid, TS_UUID_V4) {
    printf("My UUID is %s\n", TSUuidStringGet(uuid));
  }
  TSUuidDestroy(uuid);
}
const char* str = "c71e2bab-90dc-4770-9535-c9304c3de38e";
if (TS_SUCCESS == TSUuidStringParse(uuid, str)) {
  if (TS_UUID_V4 == TSUuidVersionGet(uuid)) {
    // Yes!
  }
}
```

## SEE ALSO

**[TSAPI(3ts)](/TSAPI/3ts.md)**, **TSUuid(3ts)**, **TSReturnCode(3ts)**,

## COPYRIGHT

2026, dev@trafficserver.apache.org