hal_struct man page: add volatile to example, ignore generated .3 files

Mark shared blob pointers as volatile in the example code on both RT and
userspace sides, with a note that volatile alone does not provide memory
ordering guarantees and that atomics are needed for sequence-lock fields.

Add hal_struct_attach/detach/newf.3 to docs/man/.gitignore so the
asciidoc-generated man pages are not reported as untracked.

Author: Luca Toniolo

docs/man/.gitignore

@@ -159,6 +159,9 @@ man3/hal_port_t.3
 man3/hal_port.3
 man3/hal_ready.3
 man3/hal_s32_t.3
+man3/hal_struct_attach.3
+man3/hal_struct_detach.3
+man3/hal_struct_newf.3
 man3/hal_set_constructor.3
 man3/hal_set_lock.3
 man3/hal_signal_delete.3

docs/src/man/man3/hal_struct_newf.3.adoc

@@ -78,7 +78,7 @@ RT side (in _rtapi_app_main_):
 
 ----
 typedef struct { double value; int count; } my_params_t;
-static my_params_t *params;
+static volatile my_params_t *params;
 
 my_params_t defaults = { 1.0, 0 };
 if (hal_struct_newf(comp_id, sizeof(*params), &defaults,
@@ -91,13 +91,20 @@ if (hal_struct_attach(prefix ".params", (void **)&params) < 0)
 Userspace side:
 
 ----
-my_params_t *params;
+volatile my_params_t *params;
 if (hal_struct_attach("mycomp.params", (void **)&params) < 0)
     return -1;
 /* read params->value, params->count ... */
 hal_struct_detach("mycomp.params");
 ----
 
+The pointer should be declared `volatile` on both sides so the compiler does
+not cache fields across accesses.  Note that `volatile` alone does not
+guarantee memory ordering between threads or processes.  For fields that must
+be read and written atomically (for example a sequence-lock head/tail pair),
+use C11 `_Atomic` or explicit `__atomic_*` intrinsics with an appropriate
+memory order.
+
 == SEE ALSO
 
 hal_init(3), hal_malloc(3), hal_exit(3), halcmd(1)