Improve Linux guest identification function documentation.

Make it clear that the "short name" of a Linux distro has a default
value and that the default value should not be overwritten unless
VMware does this.

If someone cheats and sends down an unsupported "short name", the
guestMapper will protect the software stack, mapping the unsupported
"short name" to that of the guestOS config found in the VMX file.
We know that is OK since the VM couldn't power on and run the guest
unless it was valid.

All older, supported ESXi have updates that contain the guestMapper.

If the guestMapper is not in place - an older, unpatched release -
the software stack can become confused causing problems and crashes.

Change augments https://github.com/vmware/open-vm-tools/pull/431

diff --git a/open-vm-tools/lib/misc/hostinfoPosix.c b/open-vm-tools/lib/misc/hostinfoPosix.c
index 5761e5baf276cd41716aa6fc3565d40d4fb4f28b..fbccdf39c50c8d05e567a6c2e20405e1152cf117 100644 (file)
--- a/open-vm-tools/lib/misc/hostinfoPosix.c
+++ b/open-vm-tools/lib/misc/hostinfoPosix.c
@@ -805,16 +805,22 @@ HostinfoESX(struct utsname *buf)  // IN:
  *      Returns distro information based on .vmx format (distroShort).
  *
  * Return value:
- *      If the short name is officially supported (by VMware)- it's recognized
- *      by the code - it will be overwritten with the official identifying
- *      short name.
+ *      The default value of the "short name", upon entry to this routine, is
+ *      the officially supported identification for a generic Linux
+ *      (otherLinux).
  *
- *      If the short name is not one of the officially support ones, there
- *      is nothing to do. The default value is the officially supported
- *      identification for a generic Linux (otherLinux). No need to change
- *      any code.
+ *      If the distro is officially supported (by VMware)- it's recognized
+ *      the code of this routine - the "short name" will be overwritten with
+ *      the officially supported "short name" of the distro. Only VMware adds
+ *      distros and related codes to this routine.
  *
- *      The long string and detailed data will fully identify what Linux
+ *      An unsupported "short name" will be ignored by the rest of the
+ *      software stack.
+ *
+ *      If the short name is not one of the officially support ones, the
+ *      default value will be left in place.
+ *
+ *      The "long name" and detailed data will fully identify what Linux
  *      is actually present.
  *
  * Side effects: