hal_pin_new(3hal)

💖 hal_pin_new 💖

okay bestie, welcome to the HAL corner of the LinuxCNC docs 🎀 this one's hal_pin_new(3hal) — it's the page that teaches you how to make a pin, and honestly? it's giving foundational. no cap.

---

✨ NAME ✨

hal_pin_new — creates a HAL pin 👑

---

✨ SYNTAX ✨

int hal_pin_bit_new(const char *name, hal_pin_dir_t dir, hal_bit_t ** data_ptr_addr, int comp_id)

int hal_pin_float_new(const char *name, hal_pin_dir_t dir, hal_float_t ** data_ptr_addr, int comp_id)

int hal_pin_u32_new(const char *name, hal_pin_dir_t dir, hal_u32_t ** data_ptr_addr, int comp_id)

int hal_pin_s32_new(const char *name, hal_pin_dir_t dir, hal_s32_t ** data_ptr_addr, int comp_id)

int hal_pin_port_new(const char *name, hal_pin_dir_t dir, hal_port_t ** data_ptr_addr, int comp_id)

int hal_pin_bit_newf(hal_pin_dir_t dir, hal_bit_t ** data_ptr_addr, int comp_id, const char *fmt, ...)

int hal_pin_float_newf(hal_pin_dir_t dir, hal_float_t ** data_ptr_addr, int comp_id, const char *fmt, ...)

int hal_pin_u32_newf(hal_pin_dir_t dir, hal_u32_t ** data_ptr_addr, int comp_id, const char *fmt, ...)

int hal_pin_s32_newf(hal_pin_dir_t dir, hal_s32_t ** data_ptr_addr, int comp_id, const char *fmt, ...)

int hal_pin_port_newf(hal_pin_dir_t dir, hal_port_t ** data_ptr_addr, int comp_id, const char *fmt, ...)

int hal_pin_new(const char *name, hal_type_t type, hal_pin_dir_t dir, void **data_ptr_addr, int comp_id)

like… look at all those little _newf twins 💅 they're the same thing but they take a fmt so you can build the name on the fly. iconic behaviour.

---

🫶 ARGUMENTS 🫶

• name — the name of the pin. yeah. that's the whole bit. 🏷️
• dir — the direction of the pin, from the viewpoint of the component. it can be one of HAL_IN, HAL_OUT, or HAL_IO. any number of HAL_IN or HAL_IO pins can be connected to the same signal, but at most one HAL_OUT pin is permitted 🚨. a component may assign a value to a pin that's HAL_OUT or HAL_IO, but it may not assign a value to a pin that's HAL_IN. that's the rule, bestie, and it is not negotiable.
• data_ptr_addr — the address of the pointer-to-data, and it must lie within memory allocated by hal_malloc. don't get cute with it 🙈
• comp_id — the HAL component identifier, handed back to you by an earlier call to hal_init. you gotta have it already, fr fr.
• fmt, — printf-style format string and arguments 🪄
• type — the type of the param, as specified in hal_type_t(3hal).

---

🌸 DESCRIPTION 🌸

so the hal_pin_new family of functions create a new pin object. that's the whole vibe. ✨

once a pin has been created, it can be linked to a signal object using hal_link. a pin contains a pointer, and the component that owns the pin can dereference that pointer to access whatever signal is linked to the pin. (and if no signal is linked? it points to a dummy signal. a little placeholder friend. we love her.)

there are functions for each of the data types that the HAL supports. and pins may only be linked to signals of the same type — no mixing, no matching, no exceptions. 💀

---

⭐ RETURN VALUE ⭐

returns 0 on success, or a negative errno value on failure. so like, check it. please. 🥺

---

👀 SEE ALSO 👀

• hal_type_t(3hal)
• hal_link(3hal)

---

ngl if you're reading this you're probably writing a HAL component and that is main character energy. go off. 🌈💜

---

mwah 💋 that's a wrap — this page comes to you from LinuxCNC Documentation, dated 2006-10-12, and it's still out here slaying. periodt. 🎀🦋