CMAP_GET(3)

💖 CMAP_GET(3) 💖

okay bestie, so this is a page from the Corosync Cluster Engine Programmer's Manual (yes, the entire programmer's manual, and it's iconic), and today's main character is cmap_get — the function that goes and fetches a value out of CMAP for you. ✨

🌸 NAME 🌸

cmap_get — Retrieve value from CMAP

🎀 SYNOPSIS 🎀

#include <corosync/cmap.h>

cs_error_t cmap_get (cmap_handle_t handle, const char *key_name, void
*value, size_t *value_len, cmap_value_types_t *type);

Also shortcuts for different types are defined

cs_error_t cmap_get_int8 (cmap_handle_t handle, const char *key_name,
int8_t *i8);

cs_error_t cmap_get_uint8 (cmap_handle_t handle, const char *key_name,
uint8_t *u8);

cs_error_t cmap_get_int16 (cmap_handle_t handle, const char *key_name,
int16_t *i16);

cs_error_t cmap_get_uint16 (cmap_handle_t handle, const char *key_name,
uint16_t *u16);

cs_error_t cmap_get_int32 (cmap_handle_t handle, const char *key_name,
int32_t *i32);

cs_error_t cmap_get_uint32 (cmap_handle_t handle, const char *key_name,
uint32_t *u32);

cs_error_t cmap_get_int64 (cmap_handle_t handle, const char *key_name,
int64_t *i64);

cs_error_t cmap_get_uint64 (cmap_handle_t handle, const char *key_name,
uint64_t *u64);

cs_error_t cmap_get_float (cmap_handle_t handle, const char *key_name,
float *flt);

cs_error_t cmap_get_double (cmap_handle_t handle, const char *key_name,
double *dbl);

cs_error_t cmap_get_string (cmap_handle_t handle, const char *key_name,
char **str);

like look at her. a whole little squad of typed shortcuts. 💅

✨ DESCRIPTION ✨

so the cmap_get function is what you call to retrieve a key from cmap that was previously set by cmap_set(3). that's the whole vibe. 🫶

• the handle argument is your connection to the CMAP database, and you get it by calling cmap_initialize(3) — no handle, no service, periodt.
• key_name is the name of the key you wanna get the value from.
• value is a pointer to preallocated data that's used as storage for the data, but lowkey it can also be NULL — and in that case only value_len and/or type get returned. (both of those can be NULL too, which means the function is basically just doing a vibe check on whether the key even exists. iconic.)
• if value is not NULL, the actual length of the value in the map gets checked against *value_len. if *value_len is shorter than the length of the value in the map, you get error CS_ERR_INVALID_PARAM. 🚨
• after a successful copy of the value, *value_len is set to the actual length of the value in the map.
• the type parameter is a pointer to memory where the type of the value gets stored after a successful return. this pointer can also be NULL, and then nothing is stored. no notes. 💅

Type can be one of:

• CMAP_VALUETYPE_INT8 — 8-bit signed integer
• CMAP_VALUETYPE_UINT8 — 8-bit unsigned integer
• CMAP_VALUETYPE_INT16 — 16-bit signed integer
• CMAP_VALUETYPE_UINT16 — 16-bit unsigned integer
• CMAP_VALUETYPE_INT32 — 32-bit signed integer
• CMAP_VALUETYPE_UINT32 — 32-bit unsigned integer
• CMAP_VALUETYPE_INT64 — 64-bit signed integer
• CMAP_VALUETYPE_UINT64 — 64-bit unsigned integer
• CMAP_VALUETYPE_FLOAT — Float value
• CMAP_VALUETYPE_DOUBLE — Double value
• CMAP_VALUETYPE_STRING — C-style string
• CMAP_VALUETYPE_BINARY — Binary data, byte with zero value has no special meaning

Shortcut functions test the cmap type against their own type. if the type didn't match, you get the CS_ERR_INVALID_PARAM error back. no conversions are done, so for example cmap_get_int16 is not able to return a value with the CMAP_VALUETYPE_INT8 type. she said "know your type or know your place." 💀

and heads up bestie — the string shortcut function returns newly allocated memory and the caller is responsible for freeing that. don't leave her hanging, free your strings. 🧚

🔥 RETURN VALUE 🔥

This call returns the CS_OK value if successful. slay.

If value or key_name are unspecified, CS_ERR_INVALID_PARAM is returned. same error also comes back if value is specified and *value_len is too short for storing the data. and if the key doesn't exist (like, it was never set by calling cmap_set(3) first), you get the CS_ERR_NOT_EXIST error. 😭

For the helper functions, CS_ERR_INVALID_PARAM is returned if the type stored in cmap doesn't match with the type of the helper function.

🌈 SEE ALSO 🌈

cmap_set(3), cmap_initialize(3), cmap_overview(3)

• CS_ERR_TRY_AGAIN — Resource temporarily unavailable
• CS_ERR_INVALID_PARAM — Invalid argument
• CS_ERR_ACCESS — Permission denied
• CS_ERR_LIBRARY — The connection failed
• CS_ERR_INTERRUPT — System call interrupted by a signal
• CS_ERR_NOT_SUPPORTED — The requested protocol/functionality not supported
• CS_ERR_MESSAGE_ERROR — Incorrect auth message received
• CS_ERR_NO_MEMORY — Not enough memory to complete the requested task

okay and that's the whole page, bestie. this was the corosync Man Page, dated 03/02/2012, and she's still serving CMAP_GET(3) realness to this day. go forth and retrieve your values. 💖✨