Miscellaneous helpers that do not fit anywhere else: byte-order conversion, base64, hex dumps, small math utilities.
Source code:
get_hostname()¶
Retrieves the hostname of the current system. On Linux, it reads from /etc/hostname, while on ESP32, it returns a default value.
const char *get_hostname(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
A pointer to a static string containing the hostname of the system.
Notes
The returned string is statically allocated and must not be modified or freed by the caller.
get_os_info()¶
The operating system of this machine (7.31.21+): what os-release(5) says of the distribution, and what uname(2) says of the kernel. The agent puts it in the card it presents to its control center, so list-agents and list-nodes show it, and info-os and info-machine answer it.
json_t *get_os_info(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
A new json object, yours to json_decref(). Every key is always there. A value the machine does not give is "".
| Key | From |
|---|---|
id | ID of /etc/os-release (else /usr/lib/os-release) |
name | NAME |
version_id | VERSION_ID |
pretty_name | PRETTY_NAME |
kernel | uname().release |
machine | uname().machine |
Example
json_t *jn_os = get_os_info();
printf("%s, kernel %s on %s\n",
kw_get_str(0, jn_os, "pretty_name", "", 0), // Debian GNU/Linux 13 (trixie)
kw_get_str(0, jn_os, "kernel", "", 0), // 6.12.116+deb13-amd64
kw_get_str(0, jn_os, "machine", "", 0) // x86_64
);
json_decref(jn_os);Notes
A value between quotes in os-release loses them, and the \ before an escaped ", \, $ or ` inside double quotes. On ESP32 it says ESP-IDF and its version.
node_uuid()¶
The node_uuid() function retrieves a unique identifier for the current machine. On Linux, it reads or generates a UUID stored in /yuneta/store/agent/uuid/uuid.json. On ESP32, it derives the UUID from the device’s MAC address.
const char *node_uuid(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
Returns a pointer to a string containing the unique node UUID.
Notes
The returned UUID is generated once and stored persistently. On ESP32, the UUID is derived from the MAC address.
On a Linux node installed from the .deb or .rpm, the file is written by /usr/libexec/yuneta/yuneta-node-uuid, which the package and both agent units run as root before an agent reads it. The UUID is a function of the machine: a reinstall gives the same UUID, two machines never give the same, and a cloned disk gets its own on its first boot. A box with an identifier burned into its chip (the devicetree serial-number, /sys/devices/soc0/serial_number) takes its UUID from it. Any other machine (x86, a VM) takes it from its DMI product_uuid AND its lowest permanent on-board MAC together (source: machine): two servers of one batch gave the same DMI UUID, and a cloned VM can keep its MAC. A random UUID only when no identifier is readable. The UUID is a version 8 UUID made from a SHA-256 of the source and its value, so it does not reveal the serial number or the MAC. The stored file is only the answer written down: when the hardware gives another UUID (a disk in other hardware, a card with a lower MAC added, a UUID of an older release), it is replaced, with a copy of the old file and a warning. It is kept only when something is missing at a start and nothing new is here (a chip that gives no value, the interface it was made from missing with the same DMI UUID and no new card). A value known as a placeholder is no identity, because every box of the model gives it (the devicetree serial-number of an Orange Pi RV2 is 0123456789ABCDEF on every board). In a container (Docker, Podman, LXC, systemd-nspawn, containerd, a BuildKit RUN step: anything out of the initial pid namespace, marker file or not) /sys is the host’s and the same for every container of it, so no hardware is read: the UUID is random and belongs to the container’s hostname, which the file records ("" when the container has none). A restart of the container keeps it. A container with another hostname makes its own, so a UUID baked into an image is not shared by the containers made from it that have other hostnames. The limit: nothing inside a container tells a copy of it from the same container re-created over its kept store, so two containers with the same hostname and the same uuid.json (an image committed from a container that has one, run twice with the same --hostname) share the UUID: delete uuid.json before a docker commit or docker export, or set a UUID in each copy. A board written from a docker export is not a container (it boots its own init in the initial pid namespace, so the /.dockerenv it keeps does not count, nor the /run/systemd/container of an Ubuntu image when /run is no tmpfs, nor the docker that systemd-detect-virt reads from them, because there only what this boot made counts): its hardware gives its own UUID, and with no hardware identifier it gets a new random UUID, not the container’s, keeping a copy of the old file. A container run with --pid=host (Toolbx and distrobox run theirs so) is in the initial pid namespace, and its / tells it: it is not the root of PID 1. Where PID 1’s root cannot be looked at (Docker’s root has no CAP_SYS_PTRACE, rootless Podman’s is in a user namespace, and a security module or the runtime can refuse any root), the mount on / is compared instead, from /proc/1/mountinfo, which anybody can read: another one is a container, the same one is the system. Where /proc/1/mountinfo cannot be read either, a root in a user namespace or without CAP_SYS_PTRACE is a container. So a root started without CAP_SYS_PTRACE on the box itself (a SysV start, an ensure by hand, a trimmed provisioning agent) reads the hardware. The package’s install stores nothing in a container (ensure --installing) and, without systemd, does not start the agents there: their first start in the container makes the UUID. An image built in a chroot (over an exported or a debootstrapped rootfs) is treated the same way: / is not the root of PID 1 (what systemd-detect-virt --chroot asks), or there is no /proc, so the install stores nothing there, and a random UUID made there all the same is not taken by a board written from the image. A random UUID stored by 7.29.2, which records no container, is kept. yuneta-node-uuid show tells what is stored and where it came from. yuneta-node-uuid set <uuid> fixes it by hand, and the hardware never changes a UUID set that way. yuneta-node-uuid unset goes back to the UUID of the hardware.
node_uuid() reads the file once per process and keeps the value in memory. When the UUID changes (a disk moved to other hardware, or set), the agents and the yunos that are running keep the old one: restart both agents, then every yuno (kill-yuno, run-yuno). The package restarts the agents only.
sudo /usr/libexec/yuneta/yuneta-node-uuid show
sudo /usr/libexec/yuneta/yuneta-node-uuid set 5a6b7c8d-1e2f-4a3b-9c4d-5e6f70819230
sudo systemctl restart yuneta_agent; sudo systemctl restart yuneta_agent22
ycommand -c 'kill-yuno'; ycommand -c 'run-yuno'Without the package (a node that builds from source and never installed it), node_uuid() writes a random UUID when the file is missing, as before.
get_inotify_self_usage()¶
How many inotify instances and watches THIS process is holding.
int get_inotify_self_usage(
int *instances,
int *watches
);Parameters
| Key | Type | Description |
|---|---|---|
instances | int * | Filled with the number of open inotify instances of this process. |
watches | int * | Filled with the number of watches those instances hold. |
Returns
0, or -1 on error.
Notes
It counts what this process uses, not the system-wide totals: the kernel limits
(max_user_instances, max_user_watches) are per user, so a leak here is what
eventually makes an unrelated daemon fail to watch anything.
check_open_fds()¶
Returns the number of currently open file descriptors in the process. On Linux, reads from /proc/self/fd. On other systems, returns 0.
int check_open_fds(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
The number of open file descriptors in the calling process. Returns 0 on non-Linux platforms.
cpu_usage()¶
Returns the accumulated CPU time of the current process in jiffies (scheduler clock ticks). On Linux, reads from /proc/self/stat. On other systems, returns 0.
uint64_t cpu_usage(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
The sum of user time (utime) and system time (stime) in jiffies. Returns 0 on non-Linux platforms.
cpu_usage_percent()¶
Calculates the CPU usage percentage of the current process over an elapsed time interval. Must be called repeatedly to track CPU usage over time.
double cpu_usage_percent(
uint64_t *last_cpu_ticks,
uint64_t *last_ms
);Parameters
| Key | Type | Description |
|---|---|---|
last_cpu_ticks | uint64_t * | IN/OUT — pointer to previous CPU ticks value. |
last_ms | uint64_t * | IN/OUT — pointer to previous timestamp in milliseconds. |
Returns
CPU usage percentage as a double ranging from 0.0 to 100.0+. Returns 0.0 on the first call or if the time interval is zero.
create_random_uuid()¶
Generates a cryptographically secure random UUID (version 4) and formats it as a string.
int create_random_uuid(
char *bf,
int bfsize
);Parameters
| Key | Type | Description |
|---|---|---|
bf | char * | Output buffer for the UUID string. |
bfsize | int | Size of the output buffer, must be at least 37 bytes. |
Returns
Returns 0 on success. Returns -1 if the buffer is too small or if random number generation fails.
free_ram_in_kb()¶
Returns the amount of free RAM available in the system in kilobytes. On Linux, reads from /proc/meminfo. On other systems, returns 0.
unsigned long free_ram_in_kb(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
The amount of free RAM in kilobytes.
get_name_from_nn_table()¶
Looks up a name string in a number-to-name lookup table by matching a numeric value.
const char *get_name_from_nn_table(
const number_name_table_t *table,
int number
);Parameters
| Key | Type | Description |
|---|---|---|
table | const number_name_table_t * | Pointer to the lookup table. |
number | int | The numeric value to search for. |
Returns
A pointer to the name string corresponding to the given number, or NULL if not found.
get_number_from_nn_table()¶
Looks up a numeric value in a number-to-name lookup table by matching a name string.
int get_number_from_nn_table(
const number_name_table_t *table,
const char *name
);Parameters
| Key | Type | Description |
|---|---|---|
table | const number_name_table_t * | Pointer to the lookup table. |
name | const char * | The name string to search for. |
Returns
The numeric value corresponding to the given name, or -1 if not found.
get_yunetas_base()¶
Resolves the Yunetas base directory path. The environment variable YUNETAS_BASE takes priority, followed by standard paths.
const char *get_yunetas_base(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
A pointer to a static string containing the Yunetas base directory path.
is_yuneta_user()¶
Checks whether a given username belongs to the “yuneta” group or is exactly the “yuneta” user.
int is_yuneta_user(
const char *username
);Parameters
| Key | Type | Description |
|---|---|---|
username | const char * | The username to check. |
Returns
Returns TRUE if the user is “yuneta” or belongs to the “yuneta” group. Returns FALSE otherwise.
print_open_fds()¶
Logs information about all currently open file descriptors in the process using a formatted prefix string.
int print_open_fds(
const char *fmt,
...
);Parameters
| Key | Type | Description |
|---|---|---|
fmt | const char * | Printf-style format string for the log prefix. |
... | variadic | Variable arguments for the format string. |
Returns
The number of open file descriptors found and logged.
sha256_digest()¶
Computes the SHA-256 (FIPS 180-4) of a buffer. Standalone: no TLS backend is involved, so it works in any yuno, whatever .config selects.
#define SHA256_DIGEST_LEN 32
void sha256_digest(
const void *data,
size_t len,
uint8_t digest[SHA256_DIGEST_LEN]
);Parameters
| Key | Type | Description |
|---|---|---|
data | const void * | The bytes to hash. |
len | size_t | Number of bytes. 0 hashes the empty input. |
digest | uint8_t [32] | Where the 32 raw bytes of the digest are written. |
Returns
Nothing: it cannot fail.
Example
uint8_t digest[SHA256_DIGEST_LEN];
sha256_digest("abc", 3, digest);
/* digest[0] == 0xba, digest[1] == 0x78, ... */sha256_hex()¶
The SHA-256 of a buffer as 64 lowercase hex characters plus the terminating nul — the form a content address or a checksum field stores. It is sha256_digest(), written out.
#define SHA256_HEX_LEN 64
int sha256_hex(
const void *data,
size_t len,
char *bf,
size_t bflen
);Parameters
| Key | Type | Description |
|---|---|---|
data | const void * | The bytes to hash. |
len | size_t | Number of bytes. |
bf | char * | Output buffer. |
bflen | size_t | Size of bf: at least SHA256_HEX_LEN + 1 (65). |
Returns
0 on success. -1 when bf is NULL or smaller than 65 bytes, with the error “buffer too small for a sha256” logged, and bf is not written.
Example
char hex[SHA256_HEX_LEN + 1];
if(sha256_hex("abc", 3, hex, sizeof(hex)) == 0) {
/* hex == "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" */
}sha256_init()¶
Starts the SHA-256 of bytes that come in parts: a file read a chunk at a time, data that arrives in frames. Give each part to sha256_update() and end with sha256_final() or sha256_final_hex(): the digest is the one of sha256_digest() over all the parts joined. The context holds no memory, so there is nothing to free. It can be a local variable, or live in a struct for as long as the parts keep coming.
typedef struct {
uint32_t h[8];
uint64_t len; // bytes hashed
uint8_t block[64]; // bytes not hashed yet, `used` of them
size_t used;
} sha256_ctx_t;
void sha256_init(
sha256_ctx_t *ctx
);Parameters
| Key | Type | Description |
|---|---|---|
ctx | sha256_ctx_t * | The context. Init it again to hash something else after a final. |
Returns
Nothing: it cannot fail.
Example
/* The sha256 of a file, 64 KB at a time */
sha256_ctx_t ctx;
char bf[65536];
char hex[SHA256_HEX_LEN + 1];
ssize_t got;
sha256_init(&ctx);
while((got = read(fd, bf, sizeof(bf))) > 0) {
sha256_update(&ctx, bf, (size_t)got);
}
sha256_final_hex(&ctx, hex, sizeof(hex));sha256_update()¶
Adds one part of the bytes to a SHA-256 started with sha256_init(). The parts can have any size, 0 included. How the bytes are cut does not change the digest.
void sha256_update(
sha256_ctx_t *ctx,
const void *data,
size_t len
);Parameters
| Key | Type | Description |
|---|---|---|
ctx | sha256_ctx_t * | The context, init’ed and not yet final. |
data | const void * | The bytes of this part. Can be NULL when len is 0. |
len | size_t | Number of bytes. |
Returns
Nothing: it cannot fail.
Example
/* "abc" given in two parts is the sha256 of "abc" */
sha256_ctx_t ctx;
char hex[SHA256_HEX_LEN + 1];
sha256_init(&ctx);
sha256_update(&ctx, "a", 1);
sha256_update(&ctx, "bc", 2);
sha256_final_hex(&ctx, hex, sizeof(hex));
/* hex == "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" */sha256_final()¶
Ends a SHA-256 started with sha256_init() and writes the 32 raw bytes of the digest. After it the context is spent: init it again to hash something else.
void sha256_final(
sha256_ctx_t *ctx,
uint8_t digest[SHA256_DIGEST_LEN]
);Parameters
| Key | Type | Description |
|---|---|---|
ctx | sha256_ctx_t * | The context. |
digest | uint8_t [32] | Where the digest is written. |
Returns
Nothing: it cannot fail.
Example
sha256_ctx_t ctx;
uint8_t digest[SHA256_DIGEST_LEN];
sha256_init(&ctx);
sha256_update(&ctx, "abc", 3);
sha256_final(&ctx, digest);
/* digest[0] == 0xba, digest[1] == 0x78, ... */sha256_final_hex()¶
sha256_final(), written out as sha256_hex() writes it: 64 lowercase hex characters and the terminating nul.
int sha256_final_hex(
sha256_ctx_t *ctx,
char *bf,
size_t bflen
);Parameters
| Key | Type | Description |
|---|---|---|
ctx | sha256_ctx_t * | The context. |
bf | char * | Output buffer. |
bflen | size_t | Size of bf: at least SHA256_HEX_LEN + 1 (65). |
Returns
0 on success, and the context is spent. -1 when bf is NULL or smaller than 65 bytes, with the error “buffer too small for a sha256” logged: bf is not written and the context is not spent, so a final with a good buffer still gives the digest.
Example
sha256_ctx_t ctx;
char hex[SHA256_HEX_LEN + 1];
sha256_init(&ctx);
sha256_update(&ctx, "", 0);
if(sha256_final_hex(&ctx, hex, sizeof(hex)) == 0) {
/* hex == "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" */
}source2base64_for_yunetas()¶
Converts a file to base64-encoded format, finding the file in either the current path or relative to the Yunetas base directory.
gbuffer_t *source2base64_for_yunetas(
const char *source,
char *comment,
int commentlen
);Parameters
| Key | Type | Description |
|---|---|---|
source | const char * | Path to the file to encode. |
comment | char * | Output buffer for error messages. |
commentlen | int | Size of the comment buffer. |
Returns
A gbuffer_t pointer containing the base64-encoded file content, or NULL if the file is not found.
total_ram_in_kb()¶
Returns the total amount of RAM installed in the system in kilobytes. On Linux, reads from /proc/meminfo.
unsigned long total_ram_in_kb(void);Parameters
| Key | Type | Description |
|---|---|---|
- | - | This function does not take any parameters. |
Returns
The total RAM in kilobytes.
yuneta_getgrnam()¶
Portable wrapper around getgrnam() that looks up group information by name. Uses static implementations when CONFIG_FULLY_STATIC is defined.
struct group *yuneta_getgrnam(
const char *name
);Parameters
| Key | Type | Description |
|---|---|---|
name | const char * | The group name to look up. |
Returns
A pointer to a struct group, or NULL if the group is not found.
yuneta_getgrouplist()¶
Portable wrapper around getgrouplist() that retrieves all groups a user belongs to.
int yuneta_getgrouplist(
const char *user,
gid_t group,
gid_t *groups,
int *ngroups
);Parameters
| Key | Type | Description |
|---|---|---|
user | const char * | The username to look up groups for. |
group | gid_t | Primary group ID. |
groups | gid_t * | Output array for group IDs. |
ngroups | int * | IN/OUT — pointer to the size of the groups array. |
Returns
The number of groups on success. Returns -1 if the array is too small.
yuneta_getpwnam()¶
Portable wrapper around getpwnam() that looks up user information by username.
struct passwd *yuneta_getpwnam(
const char *name
);Parameters
| Key | Type | Description |
|---|---|---|
name | const char * | The username to look up. |
Returns
A pointer to a struct passwd, or NULL if the username is not found.
yuneta_getpwuid()¶
Portable wrapper around getpwuid() that looks up user information by user ID.
struct passwd *yuneta_getpwuid(
uid_t uid
);Parameters
| Key | Type | Description |
|---|---|---|
uid | uid_t | The user ID to look up. |
Returns
A pointer to a struct passwd, or NULL if the user ID is not found.