COAP_STRING(3)

📦
version 4.3.5 · 11 versions
, in ubuntu stonking

🎀 COAP_STRING(3) — the libcoap manual, but make it make sense 🎀

okay so bestie, welcome to the coap_string page from the libcoap Manual ✨ this is the one that's all about "how do we hold text and how do we hold raw bytes" and honestly it's giving foundational. let's get into it 💅

🌸 NAME 🌸

coap_string, coap_new_string, coap_delete_string, coap_new_str_const, coap_delete_str_const, coap_new_binary, coap_delete_binary, coap_resize_binary, coap_new_bin_const, coap_delete_bin_const, coap_make_str_const, coap_string_equal, coap_binary_equal — literally all the CoAP string functions, together, as a treat 🫶

🦋 SYNOPSIS 🦋

#include <coap3/coap.h>

coap_string_t *coap_new_string(size_t size);

void coap_delete_string(coap_string_t *string);

coap_str_const_t *coap_new_str_const(const uint8_t *data, size_t size);

void coap_delete_str_const(coap_str_const_t *string);

coap_str_const_t *coap_make_str_const(const char *string);

int coap_string_equal(coap_string_t *string1, coap_string_t *string2);

coap_binary_t *coap_new_binary(size_t size);

void coap_delete_binary(coap_binary_t *binary);

coap_binary_t *coap_resize_binary(coap_binary_t *binary, size_t
new_size);

coap_bin_const_t *coap_new_bin_const(const uint8_t *data, size_t size);

void coap_delete_bin_const(coap_bin_const_t *binary);

int coap_binary_equal(coap_binary_t *binary1, coap_binary_t *binary2);

and now the linking tea ☕ for your specific (D)TLS library support, you link with one of:

  • -lcoap-3-notls
  • -lcoap-3-gnutls
  • -lcoap-3-openssl
  • -lcoap-3-mbedtls
  • -lcoap-3-wolfssl
  • -lcoap-3-tinydtls

otherwise (i.e. you can't pick a fave 😌) you just link with -lcoap-3 to get the default (D)TLS library support. easy.

✨ DESCRIPTION ✨

so there's support for storing strings (usually readable data, the cute stuff) and for storing binary data (the raw byte situation). a bunch of functions use these, and they're also how you get the info handed to you in some of the callbacks. main character energy for real 👑

there are 4 supported string/binary types, and here they are in all their glory:

/*
 * Coap string data definition
 */
typedef struct coap_string_t {
  size_t length;    /* length of string */
  uint8_t *s;       /* string data */
} coap_string_t;

/*
 * Coap string data definition with const data
 */
typedef struct coap_str_const_t {
  size_t length;    /* length of string */
  const uint8_t *s; /* read-only string data */
} coap_str_const_t;

/*
 * Coap binary data definition
 */
typedef struct coap_binary_t {
  size_t length;    /* length of binary data */
  uint8_t *s;       /* binary data */
} coap_binary_t;

/*
 * Coap binary data definition with const data
 */
typedef struct coap_bin_const_t {
  size_t length;    /* length of binary data */
  const uint8_t *s; /* read-only binary data */
} coap_bin_const_t;

like, notice the pattern? two of them are mutable, two of them are const and read-only. iykyk 🔥

💖 FUNCTIONS 💖

Function: coap_new_string()

coap_new_string() allocates a brand new coap_string_t of size size, where s points at uninitialized data of length size, with an extra trailing NULL sitting at size + 1. length gets set to size. she's fresh, she's empty, she's ready 🎀

Function: coap_delete_string()

coap_delete_string() is the cleanup queen — it deletes the coap_string_t that coap_new_string() made. no leaks, no crumbs 🌸

Function: coap_new_str_const()

coap_new_str_const() allocates a coap_str_const_t of size size, where s gets filled in with data and has a trailing NULL added. length is set to size. and heads up: s is read-only 🔒

Function: coap_delete_str_const()

coap_delete_str_const() deletes the coap_str_const_t that coap_new_str_const() created. tidy ✨

Function: coap_make_str_const()

coap_make_str_const() takes some read-only text and uses a static coap_str_const_t for use across different function calls. and here's the detail you don't wanna miss: there are two static entries that get cycled through, so that a single function call can call coap_make_str_const() twice. iconic design tbh 💅

Function: coap_string_equal()

coap_string_equal() compares two different string objects, string1 and string2. vibe check for strings fr fr 🦋

Function: coap_new_binary()

coap_new_binary() allocates a new coap_binary_t of size size, where s points at uninitialized data of length size. length is set to size. (no sneaky extra NULL here, just so you know 👀)

Function: coap_resize_binary()

coap_resize_binary() resizes the size of s to the new size of new_size. the data between the old length and the new_size is uninitialized — so like, don't go reading it and expecting sense 🙈 length is set to new_size.

Function: coap_delete_binary()

coap_delete_binary() deletes the coap_binary_t that coap_new_binary() created. bye bestie 👋

Function: coap_new_bin_const()

coap_new_bin_const() allocates a coap_bin_const_t of size size, where s is filled in with data and has a trailing NULL added. length is set to size. s is read-only 🔒

Function: coap_delete_bin_const()

coap_delete_bin_const() deletes the coap_bin_const_t that coap_new_bin_const() created. clean 🧚

Function: coap_binary_equal()

coap_binary_equal() compares two different binary objects, binary1 and binary2. same energy, checking if they're literally the same bytes ⭐

🌈 RETURN VALUES 🌈

  • coap_new_string() returns a pointer to an allocated coap_string_t, or NULL if something went wrong 😭
  • coap_new_str_const() returns a pointer to an allocated coap_str_const_t, or NULL if something went wrong 😭
  • coap_make_str_const() returns a pointer to a structure in static memory that has a pointer to the provided string. (static memory, bestie — don't go freeing it 💀)
  • coap_new_binary() returns a pointer to an allocated coap_binary_t, or NULL if something went wrong 😭
  • coap_resize_binary() returns a pointer to a re-allocated coap_binary_t, or NULL if something went wrong 😭
  • coap_new_bin_const() returns a pointer to an allocated coap_bin_const_t, or NULL if something went wrong 😭
  • coap_string_equal() and coap_binary_equal() return 1 on a precise match, else 0. that's it, that's the whole answer ✅

👑 SEE ALSO 👑

coap_attribute(3), coap_context(3), coap_handler(3), coap_pdu_setup(3) and coap_resource(3) — go read those next, they're all connected iykyk 🫶

🍓 FURTHER INFORMATION 🍓

see

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information. it's giving required reading 📚

💀 BUGS 💀

found a bug? please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report it — we wanna know, fr fr 🙏

got a fix instead? please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. hero behaviour 🦸‍♀️

💜 AUTHORS 💜

The libcoap project <libcoap-developers@lists.sourceforge.net> — the collective 👑

and that's the page! 💅 this was coap_string version 4.3.5, dated 08/24/2026, from the libcoap crew. go forth and manage your strings, queen 🎀✨🦋
📦 where this page comes from