[svn-r12528] Added User-Defined links to the library.

Users can create external links using H5L_create_external().  These links
point to an object in another HDF5 file.  Users can alter the behavior of
external links or create new kinds of links by registering callbacks
using the H5L interface.

Added tests, tools support, etc.

Also a number of other, minor changes have been made (some restructuring of
the H5L interface, for instance).

Additional documentation and examples are forthcoming.

5 files changed, 230 insertions, 83 deletions

diff --git a/tools/lib/h5diff.c b/tools/lib/h5diff.c
index e8c546e..4fed814 100644
--- a/tools/lib/h5diff.c
+++ b/tools/lib/h5diff.c
@@ -870,6 +870,7 @@ hsize_t diff_compare (hid_t file1_id,
  *  H5G_DATASET  Object is a dataset
  *  H5G_TYPE     Object is a named data type
  *  H5G_LINK     Object is a symbolic link
+ *  H5G_UDLINK   Object is a user-defined link
  *
  * Return: Number of differences found
  *
@@ -1067,6 +1068,90 @@ hsize_t diff (hid_t file1_id,
   }
   break;
 
+ /*-------------------------------------------------------------------------
+  * H5G_UDLINK
+  *-------------------------------------------------------------------------
+  */
+ case H5G_UDLINK:
+  {
+   char *buf1 = NULL;
+   char *buf2 = NULL;
+   H5L_linkinfo_t li1;
+   H5L_linkinfo_t li2;
+
+   if (H5Lget_linkinfo (file1_id, path1, &li1, H5P_DEFAULT) < 0)
+    goto out;
+   if (H5Lget_linkinfo (file1_id, path1, &li2, H5P_DEFAULT) < 0)
+    goto out;
+
+   /* Only external links will have a query function registered */
+   if(li1.linkclass == H5L_LINK_EXTERNAL && li2.linkclass == H5L_LINK_EXTERNAL)
+   {
+      buf1 = HDmalloc (li1.u.link_size);
+      buf2 = HDmalloc (li2.u.link_size);
+
+      if (H5Lget_linkval (file1_id, path1, li1.u.link_size, buf1, H5P_DEFAULT) < 0)
+      {
+        HDfree (buf1); HDfree (buf2);
+        goto out;
+      }
+      if (H5Lget_linkval (file2_id, path2, li2.u.link_size, buf2, H5P_DEFAULT) < 0)
+      {
+        HDfree (buf1); HDfree (buf2);
+        goto out;
+      }
+
+      /* If the buffers are the same size, compare them */
+      if(li1.u.link_size == li2.u.link_size)
+      {
+        if (H5Lget_linkval (file1_id, path1, li1.u.link_size, buf1, H5P_DEFAULT) < 0)
+        {
+          HDfree (buf1); HDfree (buf2);
+          goto out;
+        }
+        if (H5Lget_linkval (file2_id, path2, li2.u.link_size, buf2, H5P_DEFAULT) < 0)
+        {
+          HDfree (buf1); HDfree (buf2);
+          goto out;
+        }
+        ret = HDmemcmp (buf1, buf2, li1.u.link_size);
+      }
+      else
+        ret = 1;
+
+      /* if "buf1" != "buf2" then the links are "different" */
+      nfound = (ret != 0) ? 1 : 0;
+
+      if (print_objname (options, nfound))
+        parallel_print("External Link:        <%s> and <%s>\n", path1, path2);
+   }
+   else
+   {
+      /* If one or both of these links isn't an external link, we can only
+       * compare information from H5Lget_linkinfo since we don't have a query
+       * function registered for them. */
+
+      /* If the link classes or the buffer length are not the
+       * same, the links are "different"
+       */
+      if((li1.linkclass != li2.linkclass) || (li1.u.link_size != li2.u.link_size))
+        nfound = 1;
+      else
+        nfound = 0;
+
+      if (print_objname (options, nfound))
+        parallel_print("User-defined Link:        <%s> and <%s>\n", path1, path2);
+   }
+
+   /* always print the number of differences found in verbose mode */
+   if (options->m_verbose)
+    print_found(nfound);
+
+   HDfree (buf1);
+   HDfree (buf2);
+  }
+  break;
+
  default:
   nfound = 0;
   if (options->m_verbose)
diff --git a/tools/lib/h5diff_util.c b/tools/lib/h5diff_util.c
index c2c0659..4997c0c 100644
--- a/tools/lib/h5diff_util.c
+++ b/tools/lib/h5diff_util.c
@@ -269,6 +269,8 @@ get_type(int type)
   return("H5G_TYPE");
  case H5G_LINK:
   return("H5G_LINK");
+ case H5G_UDLINK:
+  return("H5G_UDLINK");
  default:
   return("user defined type");
  }
diff --git a/tools/lib/h5tools.c b/tools/lib/h5tools.c
index a4ccf63..cb62c71 100644
--- a/tools/lib/h5tools.c
+++ b/tools/lib/h5tools.c
@@ -594,12 +594,12 @@ h5tools_dump_simple_data(FILE *stream, const h5tool_format_t *info, hid_t contai
      /* Setup */
      memset(&buffer, 0, sizeof(h5tools_str_t));
      size = H5Tget_size(type);
-     
+
      if (info->line_ncols > 0)
       ncols = info->line_ncols;
-     
+
      h5tools_simple_prefix(stream, info, ctx, (hsize_t)0, 0);
-     
+
      for (i = 0; i < nelmts; i++, ctx->cur_elmt++, elmt_counter++) {
         /* Render the element */
         h5tools_str_reset(&buffer);
@@ -1340,7 +1340,7 @@ void init_acc_pos(h5tools_context_t *ctx, hsize_t *dims)
  *
  *-------------------------------------------------------------------------
  */
-static 
+static
 int do_bin_output(FILE *stream, hsize_t nelmts, hid_t tid, void *_mem)
 {
  unsigned char *mem  = (unsigned char*)_mem;
@@ -1349,7 +1349,7 @@ int do_bin_output(FILE *stream, hsize_t nelmts, hid_t tid, void *_mem)
 
  size = H5Tget_size(tid);
 
- for (i = 0; i < nelmts; i++) 
+ for (i = 0; i < nelmts; i++)
  {
   if (render_bin_output(stream,tid,mem + i * size)<0)
   {
@@ -1357,7 +1357,7 @@ int do_bin_output(FILE *stream, hsize_t nelmts, hid_t tid, void *_mem)
    return FAIL;
   }
  }
- 
+
  return SUCCEED;
 }
 
@@ -1377,7 +1377,7 @@ int do_bin_output(FILE *stream, hsize_t nelmts, hid_t tid, void *_mem)
  *
  *-------------------------------------------------------------------------
  */
-static 
+static
 int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 {
 #if 0
@@ -1407,88 +1407,88 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
   sprintf(fmt_ullong, "%%%su", H5_PRINTF_LL_WIDTH);
  }
 #endif
- 
+
  size = H5Tget_size(tid);
- 
- if (H5Tequal(tid, H5T_NATIVE_FLOAT)) 
+
+ if (H5Tequal(tid, H5T_NATIVE_FLOAT))
  {
   memcpy(&tempfloat, mem, sizeof(float));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%g ", tempfloat);
 #else
-  if (1 != fwrite(&tempfloat, size, 1, stream)) 
+  if (1 != fwrite(&tempfloat, size, 1, stream))
    return FAIL;
 #endif
- } 
- else if (H5Tequal(tid, H5T_NATIVE_DOUBLE)) 
+ }
+ else if (H5Tequal(tid, H5T_NATIVE_DOUBLE))
  {
   memcpy(&tempdouble, mem, sizeof(double));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%g ", tempdouble);
 #else
-  if (1 != fwrite(&tempdouble, size, 1, stream)) 
+  if (1 != fwrite(&tempdouble, size, 1, stream))
    return FAIL;
 #endif
- } 
+ }
 #if H5_SIZEOF_LONG_DOUBLE !=0
- else if (H5Tequal(tid, H5T_NATIVE_LDOUBLE)) 
+ else if (H5Tequal(tid, H5T_NATIVE_LDOUBLE))
  {
   memcpy(&templdouble, mem, sizeof(long double));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%Lf ", templdouble);
 #else
-  if (1 != fwrite(&templdouble, size, 1, stream)) 
+  if (1 != fwrite(&templdouble, size, 1, stream))
    return FAIL;
 #endif
  }
 #endif
- else if (H5T_STRING == H5Tget_class(tid)) 
+ else if (H5T_STRING == H5Tget_class(tid))
  {
   unsigned int i;
   H5T_str_t    pad;
   char        *s;
-  
+
   pad = H5Tget_strpad(tid);
-  
-  if(H5Tis_variable_str(tid)) 
+
+  if(H5Tis_variable_str(tid))
   {
    s = *(char**)mem;
    if(s!=NULL)
     size = HDstrlen(s);
   }
-  else 
+  else
   {
    s = mem;
    size = H5Tget_size(tid);
   }
-  for (i=0; i<size && (s[i] || pad!=H5T_STR_NULLTERM); i++) 
+  for (i=0; i<size && (s[i] || pad!=H5T_STR_NULLTERM); i++)
   {
    memcpy(&tempuchar, &s[i], sizeof(unsigned char));
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "%d", tempuchar);
 #else
-   if (1 != fwrite(&tempuchar, size, 1, stream)) 
+   if (1 != fwrite(&tempuchar, size, 1, stream))
     return FAIL;
 #endif
   } /* i */
  }
- else if (H5Tequal(tid, H5T_NATIVE_INT)) 
+ else if (H5Tequal(tid, H5T_NATIVE_INT))
  {
   memcpy(&tempint, mem, sizeof(int));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%d ", tempint);
 #else
-  if (1 != fwrite(&tempint, size, 1, stream)) 
+  if (1 != fwrite(&tempint, size, 1, stream))
    return FAIL;
 #endif
  }
- else if (H5Tequal(tid, H5T_NATIVE_UINT)) 
+ else if (H5Tequal(tid, H5T_NATIVE_UINT))
  {
   memcpy(&tempuint, mem, sizeof(unsigned int));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%u ", tempuint);
 #else
-  if (1 != fwrite(&tempuint, size, 1, stream)) 
+  if (1 != fwrite(&tempuint, size, 1, stream))
    return FAIL;
 #endif
  }
@@ -1498,17 +1498,17 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%d ", tempschar);
 #else
-  if (1 != fwrite(&tempschar, size, 1, stream)) 
+  if (1 != fwrite(&tempschar, size, 1, stream))
    return FAIL;
 #endif
- } 
+ }
  else if (H5Tequal(tid, H5T_NATIVE_UCHAR))
  {
   memcpy(&tempuchar, mem, sizeof(unsigned char));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%u ", tempuchar);
 #else
-  if (1 != fwrite(&tempuchar, size, 1, stream)) 
+  if (1 != fwrite(&tempuchar, size, 1, stream))
    return FAIL;
 #endif
  }
@@ -1518,7 +1518,7 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%d ", tempshort);
 #else
-  if (1 != fwrite(&tempshort, size, 1, stream)) 
+  if (1 != fwrite(&tempshort, size, 1, stream))
    return FAIL;
 #endif
  }
@@ -1528,7 +1528,7 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%u ", tempushort);
 #else
-  if (1 != fwrite(&tempushort, size, 1, stream)) 
+  if (1 != fwrite(&tempushort, size, 1, stream))
    return FAIL;
 #endif
  }
@@ -1538,27 +1538,27 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%ld ", templong);
 #else
-  if (1 != fwrite(&templong, size, 1, stream)) 
+  if (1 != fwrite(&templong, size, 1, stream))
    return FAIL;
 #endif
- } 
+ }
  else if (H5Tequal(tid, H5T_NATIVE_ULONG))
  {
   memcpy(&tempulong, mem, sizeof(unsigned long));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, "%lu ", tempulong);
 #else
-  if (1 != fwrite(&tempulong, size, 1, stream)) 
+  if (1 != fwrite(&tempulong, size, 1, stream))
    return FAIL;
 #endif
- } 
+ }
  else if (H5Tequal(tid, H5T_NATIVE_LLONG))
  {
   memcpy(&templlong, mem, sizeof(long_long));
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, fmt_llong, templlong);
 #else
-  if (1 != fwrite(&templlong, size, 1, stream)) 
+  if (1 != fwrite(&templlong, size, 1, stream))
    return FAIL;
 #endif
  }
@@ -1568,29 +1568,29 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
   fprintf(stream, fmt_ullong, tempullong);
 #else
-  if (1 != fwrite(&tempullong, size, 1, stream)) 
+  if (1 != fwrite(&tempullong, size, 1, stream))
    return FAIL;
 #endif
  }
- else if (H5Tequal(tid, H5T_NATIVE_HSSIZE)) 
+ else if (H5Tequal(tid, H5T_NATIVE_HSSIZE))
  {
-  if (sizeof(hssize_t) == sizeof(int)) 
+  if (sizeof(hssize_t) == sizeof(int))
   {
    memcpy(&tempint, mem, sizeof(int));
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "%d ", tempint);
 #else
-   if (1 != fwrite(&tempint, size, 1, stream)) 
+   if (1 != fwrite(&tempint, size, 1, stream))
     return FAIL;
 #endif
   }
-  else if (sizeof(hssize_t) == sizeof(long)) 
+  else if (sizeof(hssize_t) == sizeof(long))
   {
    memcpy(&templong, mem, sizeof(long));
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "%ld ", templong);
 #else
-   if (1 != fwrite(&templong, size, 1, stream)) 
+   if (1 != fwrite(&templong, size, 1, stream))
     return FAIL;
 #endif
   }
@@ -1600,30 +1600,30 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, fmt_llong, templlong);
 #else
-   if (1 != fwrite(&templlong, size, 1, stream)) 
+   if (1 != fwrite(&templlong, size, 1, stream))
     return FAIL;
 #endif
   }
- } 
- else if (H5Tequal(tid, H5T_NATIVE_HSIZE)) 
+ }
+ else if (H5Tequal(tid, H5T_NATIVE_HSIZE))
  {
-  if (sizeof(hsize_t) == sizeof(int)) 
+  if (sizeof(hsize_t) == sizeof(int))
   {
    memcpy(&tempuint, mem, sizeof(unsigned int));
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "%u ", tempuint);
 #else
-   if (1 != fwrite(&tempuint, size, 1, stream)) 
+   if (1 != fwrite(&tempuint, size, 1, stream))
     return FAIL;
 #endif
   }
-  else if (sizeof(hsize_t) == sizeof(long)) 
+  else if (sizeof(hsize_t) == sizeof(long))
   {
    memcpy(&tempulong, mem, sizeof(unsigned long));
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "%lu ", tempulong);
 #else
-   if (1 != fwrite(&tempulong, size, 1, stream)) 
+   if (1 != fwrite(&tempulong, size, 1, stream))
     return FAIL;
 #endif
   }
@@ -1633,57 +1633,57 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, fmt_ullong, tempullong);
 #else
-   if (1 != fwrite(&tempullong, size, 1, stream)) 
+   if (1 != fwrite(&tempullong, size, 1, stream))
     return FAIL;
 #endif
   }
  }
- else if (H5Tget_class(tid) == H5T_COMPOUND) 
+ else if (H5Tget_class(tid) == H5T_COMPOUND)
  {
   unsigned j;
   hid_t    memb;
   unsigned nmembs;
   size_t   offset;
-  
+
   nmembs = H5Tget_nmembers(tid);
-  
-  for (j = 0; j < nmembs; j++) 
+
+  for (j = 0; j < nmembs; j++)
   {
    offset = H5Tget_member_offset(tid, j);
    memb   = H5Tget_member_type(tid, j);
-   
+
    if (render_bin_output(stream,memb,mem + offset)<0)
     return FAIL;
-   
+
    H5Tclose(memb);
   }
  }
- else if (H5Tget_class(tid) == H5T_ENUM) 
+ else if (H5Tget_class(tid) == H5T_ENUM)
  {
   unsigned int i;
-  if (1==size) 
+  if (1==size)
   {
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "0x%02x", mem[0]);
 #else
-   if (1 != fwrite(&mem[0], size, 1, stream)) 
+   if (1 != fwrite(&mem[0], size, 1, stream))
     return FAIL;
 #endif
-  } 
-  else 
+  }
+  else
   {
    for (i = 0; i < size; i++)
    {
 #ifdef DEBUG_H5DUMP_BIN
     fprintf(stream, "%s%02x", i?":":"", mem[i]);
 #else
-    if (1 != fwrite(&mem[i], sizeof(char), 1, stream)) 
+    if (1 != fwrite(&mem[i], sizeof(char), 1, stream))
      return FAIL;
 #endif
    } /*i*/
   }/*else 1 */
  }
- else if (H5Tget_class(tid) == H5T_ARRAY) 
+ else if (H5Tget_class(tid) == H5T_ARRAY)
  {
   int     k, ndims;
   hsize_t i, dims[H5S_MAX_RANK], temp_nelmts, nelmts;
@@ -1703,63 +1703,63 @@ int render_bin_output(FILE *stream, hid_t tid, void *_mem)
    temp_nelmts *= dims[k];
    nelmts = (size_t)temp_nelmts;
   }
-   
+
   /* dump the array element */
-  for (i = 0; i < nelmts; i++) 
+  for (i = 0; i < nelmts; i++)
   {
    if (render_bin_output(stream,memb,mem + i * size)<0)
     return FAIL;
   }
-  
+
   H5Tclose(memb);
  }
- else if (H5Tget_class(tid) == H5T_VLEN) 
+ else if (H5Tget_class(tid) == H5T_VLEN)
  {
   unsigned int i;
   hsize_t nelmts;
   hid_t   memb;
-  
+
   /* get the VL sequences's base datatype for each element */
   memb = H5Tget_super(tid);
   size = H5Tget_size(memb);
- 
+
   /* Get the number of sequence elements */
   nelmts = ((hvl_t *)mem)->len;
-  
-  for (i = 0; i < nelmts; i++) 
+
+  for (i = 0; i < nelmts; i++)
   {
    /* dump the array element */
    if (render_bin_output(stream,memb,((char *)(((hvl_t *)mem)->p)) + i * size)<0)
     return FAIL;
-  } 
+  }
   H5Tclose(memb);
  }
- else 
+ else
  {
   size_t i;
-  if (1==size) 
+  if (1==size)
   {
 #ifdef DEBUG_H5DUMP_BIN
    fprintf(stream, "0x%02x", mem[0]);
 #else
-   if (1 != fwrite(&mem[0], size, 1, stream)) 
+   if (1 != fwrite(&mem[0], size, 1, stream))
     return FAIL;
 #endif
-  } 
-  else 
+  }
+  else
   {
    for (i = 0; i < size; i++)
    {
 #ifdef DEBUG_H5DUMP_BIN
     fprintf(stream, "%s%02x", i?":":"", mem[i]);
 #else
-    if (1 != fwrite(&mem[i], sizeof(char), 1, stream)) 
+    if (1 != fwrite(&mem[i], sizeof(char), 1, stream))
      return FAIL;
 #endif
    } /*i*/
   }/*else 1 */
  }
-  
+
 
  return SUCCEED;
 }
diff --git a/tools/lib/h5tools_ref.c b/tools/lib/h5tools_ref.c
index f49cb07..5d6cfae 100644
--- a/tools/lib/h5tools_ref.c
+++ b/tools/lib/h5tools_ref.c
@@ -171,6 +171,12 @@ ref_path_table_lookup(const char *thepath)
         if(H5Gget_objinfo(thefile, thepath, TRUE, &sb)<0)
             /*  fatal error ? */
             return HADDR_UNDEF;
+    } else if(sb.type == H5G_UDLINK)
+    {
+        /* UD links can't be followed, so they always "dangle" like
+         * soft links.
+         */
+        return HADDR_UNDEF;
     } /* end if */
     objno = (haddr_t)sb.objno[0] | ((haddr_t)sb.objno[1] << (8 * sizeof(long)));
 
diff --git a/tools/lib/h5trav.c b/tools/lib/h5trav.c
index f5c6e91..2ff927c 100644
--- a/tools/lib/h5trav.c
+++ b/tools/lib/h5trav.c
@@ -462,7 +462,7 @@ static int traverse( hid_t loc_id,
    */
 
   case H5G_LINK:
-   {
+  {
     /* increment */
     inserted_objs++;
 
@@ -489,9 +489,60 @@ static int traverse( hid_t loc_id,
 
    break;
 
+  /*-------------------------------------------------------------------------
+   * H5G_UDLINK
+   *-------------------------------------------------------------------------
+   */
+
+  case H5G_UDLINK:
+  {
+    H5L_linkinfo_t linkbuf;
+
+    /* increment */
+    inserted_objs++;
+
+    /* add object to table */
+    trav_table_add(HADDR_UNDEF, path, H5G_UDLINK, table );
+
+    /* Get type of link */
+    H5E_BEGIN_TRY {
+
+    /* get link class info */
+    H5Lget_linkinfo( loc_id, path, &linkbuf, H5P_DEFAULT);
+    } H5E_END_TRY;
+
+    if(linkbuf.linkclass == H5L_LINK_EXTERNAL)
+    {
+      if (statbuf.linklen>0)
+      {
+      char *targbuf;
+      char *objname;
+
+      targbuf = HDmalloc(statbuf.linklen);
+      assert(targbuf);
+      H5Gget_linkval(loc_id,path,statbuf.linklen,targbuf);
+      H5Lunpack_elink_val(targbuf, NULL, &objname);
+      if (print)
+        printf(" %-10s %s -> %s %s\n", "ext link", path, targbuf, objname);
+      free(targbuf);
+      }
+      else
+      {
+      if (print)
+        printf(" %-10s %s ->\n", "udlink", path);
+      }
+    }
+    else  /* Unknown user-defined type */
+    {
+      if (print)
+        printf(" %-10s %s ->\n", "UD link type", path);
+    }
+  }
+  break;
+
 
   default:
-    HDfprintf(stderr, "traverse: Unknown object!\n");
+    HDfprintf(stderr, "traverse: Unknown object %d!\n", type); /* JAMES */
     return (-1);
    break;
 
@@ -548,6 +599,9 @@ void h5trav_printinfo(int nobjs, trav_info_t *travi)
   case H5G_LINK:
    printf(" %-10s %s\n", "link", travi[i].name );
    break;
+  case H5G_UDLINK:
+   printf(" %-10s %s\n", "User defined link", travi[i].name );
+   break;
   default:
    printf(" %-10s %s\n", "User defined object", travi[i].name );
    break;