*
* @param conn Handle to the connection to lldpd.
* @return The number of bytes processed or a negative integer if an error has
- * occured.
+ * occurred.
*/
ssize_t lldpctl_send(lldpctl_conn_t *conn);
* lldpctl_atom_set_int(). Unlike getters, some of those may require IO to
* achieve their goal.
*
- * An atom is reference counted. Unless documented otherwise, a function
- * returning an atom will return a new reference that should be decremented if
- * not used anymore. It is quite important to use the reference counting
- * functions correctly. Segfaults or memory leaks may occur otherwise.
+ * An atom is reference counted. The semantics are quite similar to Python and
+ * you must be careful of the ownership of a reference. It is possible to own a
+ * reference by calling @c lldpctl_atom_inc_ref(). Once the atom is not needed
+ * any more, you can abandon ownership with @c lldpctl_atom_dec_ref(). Unless
+ * documented otherwise, a function returning an atom will return a new
+ * reference (the ownership is assigned to the caller, no need to call @c
+ * lldpctl_atom_inc_ref()). Unless documented otherwise, when providing an atom
+ * to a function, the atom is usually borrowed (no change in reference
+ * counting). Currently, no function will steal ownership.
+ *
+ * It is quite important to use the reference counting functions
+ * correctly. Segfaults or memory leaks may occur otherwise. Once the reference
+ * count reaches 0, the atom is immediately freed. Reusing it will likely lead
+ * to memory corruption.
*
* @{
*/
* @param neighbor Changed neighbor.
* @param data Data provided when registering the callback.
*
- * The provided interface and neighbor atoms will have their reference count
- * decremented when the callback ends. If you want to keep a reference to it, be
- * sure to increment the reference count in the callback.
+ * The provided interface and neighbor atoms are stolen by the callback: their
+ * reference count are decremented when the callback ends. If you want to keep a
+ * reference to it, be sure to increment the reference count in the callback.
*
* @see lldpctl_watch_callback
*/
lldpctl_k_port_hidden, /**< `(I)` Is this port hidden (or should it be displayed?)? */
lldpctl_k_port_status, /**< `(IS,WO)` Operational status of this (local) port */
lldpctl_k_port_chassis, /**< `(A)` Chassis associated to the port */
+ lldpctl_k_port_ttl, /**< `(I)` TTL for port, 0 if info is attached to chassis */
lldpctl_k_port_dot3_mfs = 1300, /**< `(I)` MFS */
lldpctl_k_port_dot3_aggregid, /**< `(I)` Port aggregation ID */
lldpctl_k_chassis_cap_available, /**< `(I)` Available capabalities (see `LLDP_CAP_*`) */
lldpctl_k_chassis_cap_enabled, /**< `(I)` Enabled capabilities (see `LLDP_CAP_*`) */
lldpctl_k_chassis_mgmt, /**< `(AL)` List of management addresses */
+ lldpctl_k_chassis_ttl, /**< Deprecated */
lldpctl_k_chassis_med_type = 1900, /**< `(IS)` Chassis MED type. See `LLDP_MED_CLASS_*` */
lldpctl_k_chassis_med_cap, /**< `(I)` Available MED capabilitied. See `LLDP_MED_CAP_*` */
lldpctl_k_config_tx_hold, /**< `(I,WO)` Transmit hold interval. */
lldpctl_k_config_bond_slave_src_mac_type, /**< `(I,WO)` bond slave src mac type. */
lldpctl_k_config_lldp_portid_type, /**< `(I,WO)` LLDP PortID TLV Subtype */
+ lldpctl_k_config_lldp_agent_type, /**< `(I,WO)` LLDP agent type */
lldpctl_k_custom_tlvs = 5000, /**< `(AL)` custom TLVs */
lldpctl_k_custom_tlvs_clear, /** `(I,WO)` clear list of custom TLVs */
lldpctl_k_custom_tlv_oui, /**< `(I,WO)` custom TLV Organizationally Unique Identifier. Default is 0 (3 bytes) */
lldpctl_k_custom_tlv_oui_subtype, /**< `(I,WO)` custom TLV subtype. Default is 0 (1 byte) */
lldpctl_k_custom_tlv_oui_info_string, /**< `(I,WO)` custom TLV Organizationally Unique Identifier Information String (up to 507 bytes) */
+ lldpctl_k_custom_tlv_op, /**< `(I,WO)` custom TLV operation */
} lldpctl_key_t;
* Convenience macro to iter over every value of an iterable object.
*
* @param atom The atom you want to iterate on.
- * @param value Atom that will be used to contain each value.
+ * @param value Atom name that will be used to contain each value.
*
- * This macro behaves as a for loop. Moreover, at the end of each iteration,
- * value is deallocated. Don't use it outside of the loop!
+ * This macro behaves as a for loop. Moreover, at the end of each iteration, the
+ * reference count of the provided value is decremented. If you need to use it
+ * outside of the loop, you need to increment it.
*/
#define lldpctl_atom_foreach(atom, value) \
for (lldpctl_atom_iter_t *iter = lldpctl_atom_iter(atom); \