Import all function documentations, return code reference
into the header files, as doc comments,
in the hopes of moving the CAref.html manual to docs.epics-controls.org,
which will be done in a later PR.
Also added doc comments to some other low-hanging fruits,
for example when plain comments where near, or when it was obvious to do so.
Found here at ESS:
(all in one line)
EPICS_CA_ADDR_LIST=averylonghostname.mylabnetwork.technicalnetwork.example.com
EPICS_CA_AUTO_ADDR_LIST=NO
caget somePVnam
leads to something like this:
CA.Client.Exception...............................................
Warning: "Empty PV search address list"
Source File: ../udpiiu.cpp line 403
Current Time: Thu Jun 09 2022 10:10:47.804161447
Problem desription:
addAddrToChannelAccessAddressList() will collect what ever we specify in
EPICS_CA_ADDR_LIST for channel access.
That function will add IP-addresses to the search list.
hostnames are possible, but are ignored if longer than 32 bytes,
because buf is too short.
If a hostname can be resolved into an IP, that is fine,
if not that is "fine as well" (better say: silently ignored):
If, and only if, EPICS_CA_AUTO_ADDR_LIST=NO is given then the one
and only too long hostname will be ignored and lead to an
"Empty PV search address list".
If EPICS_CA_AUTO_ADDR_LIST=YES (or nothing) is specified, the search list
is not empty, and EPICS will search all broadcast addresses.
This will eventually lead into a timout.
Solution:
Increase the buf size in addAddrToChannelAccessAddressList() from 32 to 256
The maximum length for a hostname is 255:
https://www.ietf.org/rfc/rfc1034.txt
If we add one byte for the string terminating '\0', we need 256 bytes.
And yes, this patch neglets the fact that a user can specify HOSTNAME:PORT,
which may need another 6 bytes. To put it the other way around:
In this case the hostname length is limited to 250 bytes,
which is still long enough in practice.
libCa shouldn't cause an application to abort with an uncaught
exception on a machine that has timezone problems just because
we can't convert the current time into a string.
* CPP's defined() is UB outside of a #if line
* Use (void)! cast to prevent recent GCCs & glibc from warning
about ignoring the return status from chdir()
caProto.h was using IPPORT_USERRESERVED but not including itself,
meaning there was an order dependency of header inclusion when using
this header. Now there shouldn't be.
Also, RTEMS wasn't defining IPPORT_USERRESERVED, so that definition
has been added.
In some cases the license-identification header was missing,
so I added that as well. Replaced the remaining headers that
specifically identified "Versions 3.13.7 and higher".
Makefiles and the build system were deliberately excluded.
* lp-anj7/expanded-rules:
Generate module version files with new RULES_EXPAND facilities
Extend RULES_EXPAND to add more features
More generator doc updates
Document <library>_API = <stem> for Makefiles
Convert epicsShareAPI to epicsStdCall in modules/ca
Update generator script
Modify rules to allow multiple API.h libraries to be built
Convert modules/ca to use LIBCA_API instead of epicsShare
Try out a representative sample of APIs from multiple libraries
Add build rules to generate and install *API.h header files
Add script to generate *API.h headers
Modifications to allow for CA multicast listening by adding multicast address
from EPICS_CA_BEACON_ADDR_LIST (or EPICS_CA_ADDR_LIST if beacon list is empty).
Original modifications from Jim Smedinghoff, with further changes by Pierrick Hanlet.
