Link (H5L)

Links in HDF5 file

Description

Use the MATLAB^® HDF5 link interface, H5L, to create and manipulate links in an HDF5 group. This interface includes functions that enable the creation and use of user-defined link classes.

Functions

H5L.copy

Copy link from source location to destination location

H5L.copy(srcID,srcname,destID,destname,lcplID,laplID) copies the link specified by srcname from the file or group specified by srcID to the destination destID. The new copy of the link is created with the name destname.

 Details

Input Arguments

• srcID — Group or file identifier of source link.

• srcname — Name of the source link in the file or group.

• destID — Identifier of the current file or a group in the current file. If destID is the file identifier, H5L.copy the copy is placed in the root group of the file.

• destname — Name of the copy of the link.

• lcplID — Link creation property list identifier.

• laplID — Link access property list identifier.

H5L.create_external

Create soft link to external object

H5L.create_external(filename,objname,linkID,linkname,lcplID,laplID) creates a soft link to an object in a different file.

 Details

Input Arguments

• filename — Target file containing the target object.

• objname — Path to the target object within that file. The objname argument must start at the root group of the file, but is not interpreted until lookup time.

• linkID — File or group identifier of new link.

• linkname — Name of new link, and is interpreted relative to linkID.

• lcplID — Link creation property list identifier associated with new link.

• laplID — Link access property list identifier associated with new link.

H5L.create_hard

Create hard link

H5L.create_hard(objID,objname,linkID,linkname,lcplID,laplID) creates a new hard link to a preexisting object in an HDF5 file. The new link may be one of many that point to that object.

 Details

Input Arguments

• objID — Identifier of target object, the object to which the new hard link points.

• objname — Name of target object, the object to which the new hard link points.

• linkID — File or group identifier of new link.

• linkname — Name of new link, and is interpreted relative to linkID.

• lcplID — Link creation property list identifier associated with new link.

• laplID — Link access property list identifier associated with new link.

H5L.create_soft

Create soft link

H5L.create_soft(targetPath,linkID,linkname,lcplID,laplID) creates a new soft link to an object in an HDF5 file. The new link may be one of many that point to that object i.e., the object that the new soft link points to.

 Details

Input Arguments

• targetPath — Path to the target object, the object that the new soft link points to. The targetPath can be anything and is interpreted at lookup time. This targetPath may be absolute in the file or relative to linkID.

• linkID — File or group identifier of new link.

• linkname — Name of new link, and is interpreted relative to linkID.

• lcplID — Link creation property list identifier associated with new link.

• laplID — Link access property list identifier associated with new link.

H5L.delete

Remove link

H5L.delete(locID,name,laplID) removes the link specified by name from the location locID based on the link access property list identifier specified by laplID.

H5L.exists

Determine if link exists

output = H5L.exists(locID,linkname,laplID) returns a positive value if the link specified by the pairing of the object identifier locID and the name linkname, based on the link access property list identifier specified by laplID, exists. If this link does not exist, H5L.exists can return 0 or generate an error. For further details, see the HDF5 documentation.

H5L.get_info

Information about link

linkStruct = H5L.get_info(locID,linkname,laplID) returns information about a link. A file or group identifier, locID, specifies the location of the link. The linkname argument, interpreted relative to linkID, specifies the link being queried.

H5L.get_name_by_idx

Information about link specified by index

name = H5L.get_name_by_idx(locID,groupname,idxtype,order,n,laplID) retrieves information about a link at index n present in group groupname at location locID.

name = H5L.get_name_by_idx(locID,groupname,idxtype,order,n,laplID,"TextEncoding",encoding) additionally specifies the text encoding to use to interpret the link name.

 Details

Input Arguments

• locID — Group identifier.

• groupname — Name of group.

• idxtype — Type of index, specified as one of these string scalars or character vectors:

  • "H5_INDEX_NAME" — Alpha-numeric index by attribute name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these string scalars or character vectors:

  • "H5_ITER_INC" — Iteration from beginning to end.

  • "H5_ITER_DEC" — Iteration from end to beginning.

  • "H5_ITER_NATIVE" — Iteration in the fastest available order.

• n— Link for which to retrieve information.

• laplID — Link access property list identifier for querying the group.

• encoding — Text encoding, specified as one of these values:

  • "system" — Use the system default encoding to interpret the link name.

  • "UTF-8" — Use UTF-8 encoding to interpret the link name.

H5L.get_val

Value of symbolic link

linkval = H5L.get_val(linklocID,linkname,laplID) returns the value of a symbolic link. This function corresponds to the H5L.get_val and H5Lunpack_elink_val functions in the HDF5 1.8 C API.

linkval = H5L.get_val(linklocID,linkname,laplID,"TextEncoding",encoding) additionally specifies the text encoding to use to interpret the link value.

 Details

Input Arguments

• linklocID — File or group identifier.

• linkname — Name of symbolic link and is defined relative to linklocID. Symbolic links can be soft links, external links, or certain user-defined links. In the case of soft links, linkval is a cell array containing the path to which the link points. In the case of external links, linkval is a cell array consisting of the name of the target file and the object name.

• laplID — Link access property list identifier.

• encoding — Text encoding, specified as one of these values:

  • "system" — Use the system default encoding to interpret the link name.

  • "UTF-8" — Use UTF-8 encoding to interpret the link name.

Output Arguments

• linkval — Value of symbolic link. In the case of soft links, linkval is a cell array containing the path to which the link points. In the case of external links, linkval is a cell array consisting of the name of the target file and the object name.

H5L.iterate

Iterate through links in group or file specified by group or file identifier

[status,idxOut,opdataOut] = H5L.iterate(groupID,idxtype,order,idxIn,fnc,opdataIn) iterates through the links in the group or file specified by groupID to perform a common function whose function handle is fnc. H5L.iterate does not recursively follow links into subgroups of the specified group.

 Details

Input Arguments

• groupID — Identifier of the group or file.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. If the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Specify idxtype as one of these values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

  • "H5_ITER_INC" — Iteration from beginning to end.

  • "H5_ITER_DEC" — Iteration from end to beginning.

  • "H5_ITER_NATIVE" — Iteration in the fastest available order.

• idxIn — Link index at which iteration begins.

• fnc — Callback function handle with this signature: [f_status,f_opdataOut] = fnc(f_groupID,linkname,f_opdataIn).

  Input Arguments for fnc

  • f_groupID — Populated with groupID input argument.

  • linkname — Name of current link.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All links were processed.

  • positive — Short-circuit success. The value is the index value of the last link that was processed.

  • negative — Failure.

• idxOut — Index at which iteration was stopped. This value can be used to resume an interrupted iteration.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

Note

The index type passed in idxtype is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

H5L.iterate_by_name

Iterate through links in group or file specified by location and group name

[status,idxOut,opdataOut] = H5L.iterate_by_name(locID,groupname,idxtype,order,idxIn,fnc,opdataIn,laplID) iterates through the links in a group or file to perform a common function whose function handle is fnc. The starting point of the iteration is determined by a location identifier and a relative group name. H5L.iterate_by_name does not recursively follow links into subgroups of the specified group. A link access property list, laplID, may affect the outcome depending upon the type of link being traversed.

 Details

Input Arguments

• locID — Identifier of the group or file.

• groupname — Name of the group.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. If the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Specify idxtype as one of these values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

  • "H5_ITER_INC" — Iteration from beginning to end.

  • "H5_ITER_DEC" — Iteration from end to beginning.

  • "H5_ITER_NATIVE" — Iteration in the fastest available order.

• idxIn — Link index at which iteration begins.

• fnc — Callback function handle with this signature: [f_status,f_opdataOut] = fnc(groupID,linkname,f_opdataIn).

  Input Arguments for fnc

  • groupID — Populated with locID input argument.

  • linkname — Name of current link.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

• laplID — Identifier of link access property list. A link access property list can affect the outcome if links are involved. When default link access properties are acceptable, "H5P_DEFAULT" can be used.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All links were processed.

  • positive — Short-circuit success. The value is the index value of the last link that was processed.

  • negative — Failure.

• idxOut — Index at which iteration was stopped. This value can be used to resume an interrupted iteration.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

Note

The index type passed in idxtype is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

H5L.move

Rename link

H5L.move(srcID,srcname,destID,destname,lcplID,laplID) renames a link within an HDF5 file. The original link, srcname, is removed from the group graph and the new link, destname, is inserted. This change is accomplished as an atomic operation.

 Details

Input Arguments

• srcID — File or group identifier associated with existing link.

• srcname — Path to existing link and is interpreted relative to srcID.

• destID — File or group identifier associated with link to use to replace srcname in the group graph.

• destname — Name of new link.

• lcplID — Link creation property list identifier.

• laplID — Link access property list identifier.

H5L.visit

Recursively iterate through links in group or file specified by group or file identifier

[status,opdataOut] = H5L.visit(groupID,idxtype,order,fnc,opdataIn) recursively iterates through all links in and below the group or file specified by groupID to perform a common function whose function handle is fnc.

 Details

Input Arguments

• groupID — Identifier of the group or file.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. If the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Specify idxtype as one of these values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

  • "H5_ITER_INC" — Iteration from beginning to end.

  • "H5_ITER_DEC" — Iteration from end to beginning.

  • "H5_ITER_NATIVE" — Iteration in the fastest available order.

• fnc — Callback function handle with this signature: [f_status,f_opdataOut] = fnc(f_groupID,linkname,f_opdataIn).

  Input Arguments for fnc

  • f_groupID — Populated with groupID input argument.

  • linkname — Name of current link.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All links were processed.

  • positive — Short-circuit success. The value is the index value of the last link that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

Note

The index type passed in idxtype is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

H5L.visit_by_name

Recursively iterate through links in group or file specified by location and group name

[status,opdataOut] = H5L.visit_by_name(locID,groupname,idxtype,order,fnc,opdataIn,laplID) recursively iterates though all links in and below the group or file to perform a common function whose function handle is fnc. The starting point of the iteration is determined by a location identifier and a relative group name. A link access property list, laplID, may affect the outcome depending upon the type of link being traversed.

 Details

Input Arguments

• locID — Identifier of the group or file.

• groupname — Name of the group.

• idxtype — Type of index. If the links have not been indexed by the index type, they will be sorted by that index before the iteration begins. If the links have been so indexed, the sorting step will be unnecessary, so the iteration may begin more quickly. Specify idxtype as one of these values or their numeric equivalents:

  • "H5_INDEX_NAME" — Alpha-numeric index by link name.

  • "H5_INDEX_CRT_ORDER" — Index by creation order.

• order — Index traversal order, specified as one of these values or their numeric equivalents:

  • "H5_ITER_INC" — Iteration from beginning to end.

  • "H5_ITER_DEC" — Iteration from end to beginning.

  • "H5_ITER_NATIVE" — Iteration in the fastest available order.

• fnc — Callback function handle with this signature: [f_status,f_opdataOut] = fnc(groupID,linkname,f_opdataIn).

  Input Arguments for fnc

  • groupID — Populated with locID input argument.

  • linkname — Name of current link.

  • f_opdataIn — Initially populated by opdataIn input argument; thereafter populated by f_opdataOut output argument of fnc from the previous iteration step.

  Output Arguments for fnc

  • f_status — Status indicator, interpreted as follows:

    • zero — Continues with the iteration, or populates status output argument if all members have been processed.

    • nonzero — Stops the iteration and populates the status output argument.

  • f_opdataOut — Value that populates the f_opdataIn input argument of fnc for the next iteration step. The final f_opdataOut at the end of the iteration populates the opdataOut output argument.

• opdataIn — User-defined value or structure that populates the f_opdataIn input argument of fnc in the first step of the iteration.

• laplID — Identifier of link access property list. A link access property list can affect the outcome if links are involved. When default link access properties are acceptable, "H5P_DEFAULT" can be used.

Output Arguments

• status — Populated by the final f_status output argument of fnc at the end of the iteration and interpreted as follows:

  • zero — Success. All links were processed.

  • positive — Short-circuit success. The value is the index value of the last link that was processed.

  • negative — Failure.

• opdataOut — Populated by the final f_opdataOut output argument of fnc at the end of the iteration.

Note

The index type passed in idxtype is a best effort setting. If the application passes in a value indicating iteration in creation order and a group is encountered that was not tracked in creation order, that group will be iterated over in alpha-numeric order by name, or name order. (Name order is the native order used by the HDF5 Library and is always available.)

Examples

Remove Only Link to Group

Remove the only link to the /g3 group in example.h5.

srcFile = fullfile(matlabroot,"toolbox","matlab","demos","example.h5");
copyfile(srcFile,"myfile.h5");
fileattrib("myfile.h5","+w");
fid = H5F.open("myfile.h5","H5F_ACC_RDWR","H5P_DEFAULT");
H5L.delete(fid,"g3","H5P_DEFAULT");
H5F.close(fid);

Determine If Link Exists

fid = H5F.open("example.h5");
gid = H5G.open(fid,"/g1/g1.2/g1.2.1");
if H5L.exists(gid,"slink","H5P_DEFAULT")
    fprintf("link exists\n");
else
    fprintf("link does not exist\n");
end
H5G.close(gid);
H5F.close(fid);

Rename Group in HDF5 File

Rename the /g2 group to /g2/g3.

srcFile = fullfile(matlabroot,"toolbox","matlab","demos","example.h5");
copyfile(srcFile,"myfile.h5");
fileattrib("myfile.h5","+w");
fid = H5F.open("myfile.h5","H5F_ACC_RDWR","H5P_DEFAULT");
g2id = H5G.open(fid,"g2");
H5L.move(fid,"g3",g2id,"g3","H5P_DEFAULT","H5P_DEFAULT");
H5G.close(g2id);
H5F.close(fid);

Version History

Introduced before R2006a