The subroutines that constitute the DMF user command application program interface (API) are available to user-written programs by linking to the DMF user library, libdmfusr.so. Sites can design and write their own custom DMF user commands, which eliminates the need to use wrapper scripts around the DMF user commands.
This appendix discusses the following:
The distributed command feature allows DMF commands to execute on a host other than the host on which the DMF daemon is running. (This feature was first made available with DMF 2.7.) A host that imports DMF-managed filesystems from the DMF daemon host machine can execute the DMF commands locally as defined in “Hardware and Software Requirements” in Chapter 1.
The DMF user commands communicate with a process named dmusrcmd, which is executed as setuid root. dmusrcmd performs validity checks and communicates with the DMF daemon. (In releases prior to DMF 2.7, user commands communicated directly with the DMF daemon and were installed as setuid root processes.)
In order for the DMF user commands to communicate in an efficient and consistent manner with the dmusrcmd process, they must access the DMF user library, libdmfusr.so[.n], which is installed in the following directories:
IRIX platforms:
/usr/lib /usr/lib32 /usr/lib64 All other platforms:
/usr/lib
Each of the DMF user commands is linked to the library for its protocol-based communications. (The DMF user library became a versioned shared-object library in DMF 3.1. See “libdmfusr.so Library Versioning” for more information on accessing the correct version of libdmfusr.so.)
The underlying design of the API calls for the user command to make contact with a dmusrcmd process by creating an opaque context object via a call to the API. This context is then used as a parameter on each function API call (put, get, fullstat, or copy). The context is used by each API subroutine to perform the requested operation and to correctly return the results of the operation to the command.
In addition to the library, the libdmfusr.H, libdmfcom.H, and dmu_err.h header files are provided. These files are required for sites to effectively create their own commands. All header files are installed in /usr/include/dmf . The libdmf* header files contain all of the object and function prototype definitions required by the API subroutine calls. The dmu_err.h file contains all of the API error code definitions. Along with each error code definition is a text string that is associated with each of the error codes. This text string is the same message that is generated automatically when the error occurs as part of the DmuErrInfo_t object (see “DmuErrInfo_t”). The text string is included in the file as informational only, and is not accessible by a program that includes dmu_err.h.
Each type of function request (put, get, fullstat, or copy) can be made via a synchronous or an asynchronous API subroutine call:
Synchronous subroutine calls do not return to the caller until the request has completed, either successfully or unsuccessfully. These synchronous subroutines return an error object to the caller that can be processed to determine the success or failure of the call. If an application is making more than one call, these calls will usually perform less efficiently than their asynchronous counterparts because of the serial nature of their activity.
Asynchronous subroutine calls return immediately to the caller. The return codes of these asynchronous subroutines indicate whether the request was successfully forwarded to dmusrcmd for processing. A successful return allows the calling program to continue its own processing in parallel with the processing being performed by dmusrcmd (or the DMF daemon) to complete the request. If the request was successfully forwarded, a request ID that is unique within the scope of the opaque context is returned to the caller. It is the responsibility of the caller to associate the request ID with the correct completion object (described in “DmuCompletion_t”) to determine the eventual result of the original request.
There are several API subroutine calls for processing asynchronous request completion objects. The user can choose to do any of the following:
Be notified when all requests have completed without processing the return status of each request.
Process the return status of each request in the order in which they complete.
Wait synchronously on an individual asynchronous request's completion by specifying the request ID on which to wait. By using this method, each request return status can be processed in the order in which it was sent, known as request ID order.
The API includes well-defined protocols that it uses to communicate with the dmusrcmd process. Because these protocols make use of the pthreads(5) mechanism, any user application program making use of the API via libdmfusr.so must also link to the libpthread.so shared object library via one of the following:
| -lpthread compiler option using cc(1) or CC(1) |
| -lpthread loader option using ld(1) or rld(1) |
In many cases, the API subroutines pass the address of an object back to the caller by setting a ** pointer accordingly. If errors occur and the subroutine is unable to complete its task, the address returned may be NULL. It is up to the caller to check the validity of an object's address before using it in order to avoid causing a SIGSEGV fault in the application program.
The DMF user library for each IRIX platform (lib, lib32, and lib64) was compiled using a MIPSpro compiler. Compiling user applications that call DMF user library API subroutines with compilers other than MIPSpro compilers may result in incompatibilities causing load-time or run-time errors.
DMF 3.1 introduced a new version of the DMF user library. This new version is not compatible with the previous library nor with applications that were written and linked with the previous library. To allow the use of older applications after installing DMF 3.2 and to facilitate upgrading older applications, DMF 3.2 provides both the old version and the new version and introduces a linking mechanism.
When an application is created and linked with a shared object, the name of the actual library that the application is ultimately linked with is stored in the executable file and used at execution time to find a library of the same name for dynamic linking. In previous releases, the library was named libdmfusr.so. Therefore, all existing DMF commands and site-developed applications that use the library contain the filename libdmfusr.so in the executable for linking with the library at execution time.
A common practice when creating a new version of a library is to add the suffix .n to the library name, where n is an ever-increasing integer that refers to the current version number.
In previous releases of DMF, the library named libdmfusr.so was an actual library, rather than a link to a library. DMF 3.2 provides the old library (renamed libdmfusr.so.1) and the new library (named libdmfusr.so.2). All DMF 3.2 user commands (such as dmput) were created and linked with libdmfusr.so.2 and their executables contain the filename libdmfusr.so.2 for linking with the library.
The libdmfusr.so.1 library is identical to the libdmfusr.so library shipped prior to DMF 3.1. The DMF 3.2 installation process will install a link named libdmfusr.so that will point to libdmfusr.so.2. If needed, you can change the link to point to libdmfusr.so.1 in order to satisfy linking for executables built with a pre-DMF 3.1 libdmfusr.so .
The locations of the libraries and the link have not changed from previous releases (see “Overview of the Distributed Command Feature and libdmfusr.so”).
The new libdmfusr.so link provides the following advantages:
You can use the default setting, which does not require any knowledge about the latest version of the library. When developing new site applications using the library, the non-version-specific ld option -ldmfusr will result in the loader following the link and using the new version of the library, libdmfusr.so.2. The resulting applications will contain the name libdmfusr.so.2 in their executable files for dynamic loading.
You can reset the link to point to libdmfusr.so.1 , which allows existing site-developed applications to continue to work with the older version of the library. This will not affect any of the DMF user commands because they contain the name of the new library and make no use of the link at execution time. When an older application executes, if filename libdmfusr.so is encountered by the loader and the link points to libdmfusr.so.1, the application will continue to work exactly as it did before the DMF 3.2 installation.
The two uses of the link as described above are mutually exclusive of each other. Take care when using the link to enable older applications to run with the old library while at the same time developing new applications using the new library. If the link points to libdmfusr.so.1 and -ldmfusr is used to create a new application, the older version of the library will be found and the resulting executable will contain the filename libdmfusr.so.1 for use at execution time. If older applications are required to run correctly while new applications are being developed, you must use specific loader command options to ensure that the new applications are linked with the latest library. This can be done by including the specific library name, such as libdmfusr.so.2, on the ld or cc command instead of the generic library specification -ldmfusr.
The data types described in this section are defined in libdmfusr.H or libdmfcom.H. For the most up-to-date definitions of each of these types, see the appropriate file. The following information is provided as a general description and overall usage outline.
All of the data types defined in this section are C++ objects, and all have constructors and destructors. Many have copy constructors and some have operator override functions defined. Please refer to the appropriate .H header file to see what C++ functions are defined for each object in addition to the member functions described in this section.
The DmuAllErrors_t object provides the caller with as much information regarding errors as is practical. The complex nature of the API and its communications allows for many types of errors and several locations (processes) in which they can occur. For example, a request might fail in the API, in the dmusrcmd process, or in the DMF daemon.
The public member fields and functions of this class are as follows:
| entry | Specifies a read-only pointer allowing access to all DmuErrInfo_t entries in the DmuAllErrors_t internal array. | |
| numErrors() | Returns the number of DmuErrInfo_t entries in the DmuAllErrors_t internal array. | |
| resetErrors() | Clears the DmuAllErrors_t internal array. |
Following is an example using a DmuAllErrors_t object.
 | Note: The following code is a guideline. It may refer to elements of a DmuAllErrors_t structure that are not defined in your installed version of libdmfcom.H. |
report_errors(DmuAllErrors_t *errs)
{
int i;
if (!errs) {
return;
}
for (i = 0; i < errs->numErrors(); i++) {
fprintf(stdout, "group '%s' errcode '%d' who '%s' "
"severity '%s' position '%s' host '%s' message '%s'\n",
errs->entry[i].group ? errs->entry[i].group : "NULL",
errs->entry[i].errcode,
DmuLogGetErrWhoImage(errs->entry[i].errwho),
DmuLogGetSeverityImage(errs->entry[i].severity),
errs->entry[i].position ? errs->entry[i].position : "NULL",
errs->entry[i].host ? errs->entry[i].host : "NULL",
errs->entry[i].message ? errs->entry[i].message : "NULL");
}
} |
The DmuAttr_t object defines the DMF attribute for a DMF-managed file.
The public member fields and functions of this class are as follows:
| bfid | Specifies a DmuBfid_t object (defined in libdmfcom.H) that defines the file's bitfile-ID (bfid). | |||||||||||||||||||
| fsys | Specifies a DmuFileIoMethod_t object (defined in libdmfcom.H) that defines the file's filesystem type. | |||||||||||||||||||
| version | Specifies a DmuFileIoVersion_t object (defined in libdmfcom.H) that defines the filesystem version. | |||||||||||||||||||
| dmstate | Specifies a dmu_state_t object that defines the file state. Valid states are:
| |||||||||||||||||||
| dmflags | Specifies an integer defining a file's DMAPI flags. Currently unused. | |||||||||||||||||||
| sitetag | Defines the file site tag value. See dmtag(1). | |||||||||||||||||||
| regbuf | Specifies a DmuFullRegbuf_t object that defines the file full region information. See “DmuFullRegbuf_t”. |
The DmuByteRange_t object defines a range of bytes that are to be associated with a put or get request.
The public member fields and functions of this class are as follows:
| start_off | Starting offset in bytes of the range in the file. | |
| end_off | Ending offset in bytes of the range in the file. |
Nonnegative values for start_off or end_off indicate an offset from the beginning of the file. The first byte in the file has offset 0. Negative values may be used to indicate an offset from the end of the file. The value -1 indicates the last byte in the file, -2 is the next-to-last byte, and so on. The range is inclusive, so if start_off has a value of 2 and end_off has a value of 2, it indicates a range of one byte.
The DmuByteRanges_t object defines a set of DmuByteRange_t objects that are to be associated with a put or get request.
The public member fields and functions of this class are as follows:
| rounding | |||||
Specifies the rounding method to be used to validate range addresses. Only DMU_RND_NONE is valid. | |||||
| entry | |||||
Specifies a read-only pointer allowing access to all DmuByteRange_t entries in the DmuByteRanges_t internal array. | |||||
| numByteRanges() | |||||
Returns the number of DmuByteRange_t objects contained in the entry array. | |||||
| resetByteRanges() | |||||
Resets the number of DmuByteRange_t objects in the array to zero. | |||||
| setByteRange() | |||||
Adds a new range. If the range being added overlaps or is adjacent to an existing range in the array, the items may be coalesced. It is expected that the starting offset not be closer to the end-of-file than the ending offset. For example, a starting offset of 5 and an ending offset of 4 is invalid, and the setByteRange() function may not add it to the array. The setByteRange() function cannot determine the validity of some ranges, however, and may add ranges that the put or get request will later ignore. | |||||
| fromByteRangesImage() | |||||
Converts a string that represents a byte range and adds it to the DmuByteRanges_t object. Strings that represent byte ranges are described on the dmput man page.
If the byte range overlaps or is adjacent to an existing range in the array, the items may be coalesced. | |||||
| clearByteRange | |||||
Clears the specified byte range in the DmuByteRanges_t object. The clearByteRange() routine is restricted in how it handles negative offsets, both in the DmuByteRange_t members of the DmuByteRanges_t class and in its parameters. The following items give the details of these restrictions. In the following items, start and end are the parameters to the clearByteRange() routine, using the following format:
| |||||
You can create a valid DmuByteRanges_t object using the default constructor with or without the new operator, depending on the need. For example:
DmuByteRanges_t ranges; DmuByteRanges_t *ranges = new DmuByteRanges_t; |
The following example creates a DmuByteRanges_t named byteranges, adds a DmuByteRange_t to it, then prints the entry to stdout:
DmuByteRanges_t byteranges;
int i;
byteranges.rounding = DMU_RND_NONE;
byteranges.setByteRange(0, 4095); /* specifies the first 4096 bytes in the file */
for (i = 0; i < byteranges.numByteRanges(); i++) {
fprintf(stdout,"Starting offset %lld, ending offset %lld\n",
byteranges.entry[i].start_off,
byteranges.entry[i].end_off);
} |
The output to stdout would be as follows:
starting offset 0, ending offset 4095 |
The following example creates a DmuByteRanges_t named b, adds a DmuByteRange_t to it, then clears a byte range:
DmuByteRanges_t b;
int i;
b.setByteRange(0,40960);
b.clearByteRange(4096,8191);
printf("Num byte ranges %d\n",b.numByteRanges());
for (i = 0; i < b.numByteRanges(); i++)
printf("%lld %lld\n",b.entry[i].start_off, b.entry[i].end_off); |
The output to stdout would be as follows:
Num byte ranges 2 0 4095 8192 40960 |
| Note: The toByteRangesImage() member function is not yet supported. |
The DmuCompletion_t object is returned by one of the API request completion subroutines (see “Request Completion Subroutines”) with the results of an asynchronous request.
The public member fields and functions of this class are as follows:
| request_id | Associates the completion object with an asynchronous request that was previously issued. This value coincides with the request ID value that any of the asynchronous subroutines return to the user. | |
| request_type | Specifies the type of the original request. | |
| reply_code | Contains the overall success or failure status of the request. If this value is DmuNoError, the request was successful. If not, the allerrors field should be checked for the appropriate error information. | |
| ureq_data | Specifies a pointer to user request-type specific data. For a fullstat user request, this will point to a DmuFullstat_t object. This field has no meaning for put, get, or copy user requests. | |
| fhandle | Specifies the file handle of the file associated with the request. |
The DmuCopyRange_t object defines a range of bytes that are to be associated with a copy request.
The public member fields and functions of this class are as follows:
| src_offset | Specifies the starting offset in bytes of the range in the source file to be copied. | |
| src_length | Specifies the length in bytes of the range to be copied. | |
| dst_offset | Specifies the starting offset in bytes in the destination file to which the copy is sent. |
The DmuCopyRanges_t class defines an array of DmuCopyRange_t objects that are to be associated with a copy request.
The public member fields and functions of this class are as follows:
| rounding | Specifies the rounding method to be used to validate range addresses. Only DMU_RND_NONE is supported. | |
| entry | Specifies a read-only pointer allowing access to all the DmuCopyRange_t entries in the array. | |
| numCopyRanges() | Returns the number of DmuCopyRange_t objects contained in the entry array. Only a single range is supported. | |
| setCopyRange | Adds a new DmuCopyRange_t object to the array. | |
| resetCopyRanges() | Resets the number of DmuCopyRange_t objects in the array to zero. |
Example: Create a DmuCopyRanges_t, add a DmuCopyRange_t to it, then print the entry to stdout :
DmuCopyRanges_t copyranges;
int i;
copyranges.rounding = DMU_RND_NONE;
copyranges.setCopyRange(0, 4096, 0);
for (i = 0; i < copyranges.numCopyRanges(); i++) {
fprintf(stdout, "source offset %llu, length %llu, "
"destination offset %llu\n",
copyranges.entry[i].src_offset,
copyranges.entry[i].src_length,
copyranges.entry[i].dst_offset);
} |
The DmuErrHandler_f object defines a user-specified error handling subroutine. Many of the API subroutines may result in the receipt of error information from the dmusrcmd process or the DMF daemon in the processing of the request. As these errors are received, they are formatted into a DmuErrInfo_t object (see “DmuErrInfo_t”) and are generally returned to the caller either via a calling parameter or as part of a DmuCompletion_t object.
In addition, however, if the error occurs in the course of processing internal protocol messages, the DmuErrInfo_t object can also be passed into the DmuErrHandler_f that the caller defined when the opaque context was created.
As part of the DmuCreateContext() API subroutine call, the caller can specify a site-defined DmuErrHandler_f subroutine or the caller can use one of the following API-supplied subroutines:
| DmuDefErrHandler | Outputs the severity of error and the message associated with the error to stderr. | |
| DmuNullErrHandler | Does nothing with the error. |
The DmuErrInfo_t object contains the information about a single error occurrence.
The public member fields and functions of this class are as follows:
| group | Defines the originator of the error:
| |||
| errcode | Specifies an integer value generated by the originating routine. This code may have many different meanings for a single value, depending on who the originator is. | |||
| errwho | Specifies an integer value that describes in more detail the originator of the error. Use the DmuLogGetErrWhoImage() subroutine to access a character string corresponding to this value . | |||
| severity | Specifies an integer value that describes the severity of the error. Use the DmuLogGetSeverityImage() subroutine to access a character string corresponding to this value. | |||
| position | Specifies a character pointer to a string that contains the position of where the error was generated. For example, this could be a pointer to a character string generated using the __FILE__ and __LINE__ cpp (1) macros. This field may be NULL. | |||
| host | Specifies a character pointer to a string that contains the host name where the error originated. | |||
| message | Specifies a character pointer to a string that contains the body of the error message. |
The DmuError_t object is the type that most of the API subroutines pass as a return code. The definition DmuNoError is the general success return code.
The DmuEvents_t object defines the various event mask settings that a file may contain.
Valid settings are defined as the logical OR of any of the following:
| DMF_EVENT_READ | Generates a kernel event for each read request on the file. | |
| DMF_EVENT_WRITE | Generates a kernel event for each write request on the file. | |
| DMF_EVENT_TRUNCATE | Generates a kernel event for each truncate request on the file. | |
| DMF_EVENT_DESTROY | Generates a kernel event will be generated for each destroy request on the file. |
The DmuFhandle_t object contains the ASCII representation of the file fhandle as it is known on the host on which the file's filesystem is native.
The public member fields and functions of this class are as follows:
| hanp | Specifies a character array containing the file handle. | |
| fromFhandleImage() | Copies an ASCII file handle image string into the hanp field. | |
| toFhandleImage() | Copies the hanp field into a DmuStringImage_t object. | |
| is_valid() | Verifies the validity of the hanp field. |
The DmuFullRegbuf_t object defines the DMF fullregion buffer information for a file Only a single region constituting of the whole file is supported.
The public member fields and functions of this class are as follows:
| arrcnt | Specifies the number of regions in the regions array. | |
| regcnt | Specifies the number of regions in the regions array that are valid. Only 0 and 1 are supported. | |
| regions | Specifies a DmuFullRegion_t array. See “DmuRegion_t”. |
The DmuFullstat_t object is a user-accessible version of the internal DMF fullstat object. It contains all of the basic stat(2) information regarding the file, as well as all of the DMAPI-related fields.
The public member fields and functions of this class are as follows:
| inconsistent | Indicates that the DmuFullstat_t object has inconsistencies in the fields. | |
| stat | Specifies a DmuStat_t object that contains the fields representing those in the stat(5) structure. See the stat(2) system call. | |
| evmask | Specifies a DmuEvents_t object that defines the event mask for the file. See “DmuEvents_t” | |
| regbuf | Specifies a DmuRegionbuf_t object that defines the regions of the file. See “DmuRegionbuf_t”. | |
| attr | Specifies a DmuAttr_t object that defines the DMF attribute of the file. See “DmuAttr_t”. | |
| host | Specifies the host name where the file is native. | |
| mntpt | Specifies a DmuOpaque_t object (defined in libdmfcom.H) defining the mount point of the filesystem containing the file on host. | |
| relpath | Specifies the relative path of the file in mntpt on host. | |
| is_valid() | Returns 1 if the DmuFullstat_t is valid. |
The DmuRegion_t object defines a filesystem region.
The public member fields and functions of this class are as follows:
| rg_offset | Defines the region starting offset in bytes. The start of the file is byte 0. | |
| rg_size | Defines the region size in bytes. | |
| rg_flags | Defines the region event flag bitmask. See “DmuEvents_t”. |
The DmuRegionbuf_t object defines the filesystem region buffer information for a file. Only a single region constituting the whole file is supported.
The public member fields and functions of this class are as follows:
| arrcnt | Specifies the number of regions in the regions array. | |
| regcnt | Specifies the number of regions in the regions array that are valid. Only 0 and 1 are supported. | |
| regions | Specifies the DmuRegion_t array. See the DmuRegion_t description. |
The DmuReplyOrder_t object is used to select the order in which asynchronous replies are to be returned by the API reply processing subroutines.
Valid settings are defined as follows:
| DmuAnyOrder | Returns replies in the order the replies are received. | |
| DmuReqOrder | Returns replies in the order the requests were issued. |
The DmuReplyType_t object is used to select the type of reply that an API can receive after sending a request. All requests will receive a final reply when the dmusrcmd process has completed processing the request whether it was successful or not.
Valid settings are defined as follows:
| DmuIntermed | Specifies an intermediate reply. An informational message to alert the caller that the request is being processed and may not complete for some time. An example of this is the intermediate reply that is sent when a put request has been forwarded to an MSP or LS for processing and that the completion reply is deferred until that operation is complete. | |
| DmuFinal | Specifies the final reply for the request. |
This definition is used to specify the types of replies that some of the reply processing subroutines defined below are to consider.
The DmuSeverity_t object specifies the level of message reporting.
Valid settings are defined as follows:
| DmuSevDebug4 | Highest level of debug reporting. | |
| DmuSevDebug3 | Second-highest level of debug reporting. | |
| DmuSevDebug2 | Third-highest level of debug reporting. | |
| DmuSevDebug1 | Lowest level of debug reporting. | |
| DmuSevVerbose | Verbose message reporting. | |
| DmuSevInform | Informative message reporting. | |
| DmuSevWarn | Warning message reporting. | |
| DmuSevFatal | Error message reporting. |
The DmuVolGroup_t object defines a volume group name. As an entry in a DmuVolGroups_t array, it is used to specify one of the volume groups to be used for a DMF put request. For more information about volume groups, see “How DMF Works” in Chapter 1.
The public member field and function of this class is as follows:
| vgname | Specifies a character pointer to string containing the name of a valid volume group. |
The DmuVolGroups_t object defines an array of DmuVolGroup_t objects. This object is used to specify the list of volume groups to which a caller would like a file to be written in a DMF put request.
The public member fields and functions of this class are as follows:
| setVolGroup() | Adds a DmuVolGroup_t object to the internal DmuVolGroup_t array. | ||
| clearVolGroup() | Removes a DmuVolGroup_t object from the internal DmuVolGroup_t array. | ||
| numVolGroups() | Returns the number of DmuVolGroup_t objects in the internal DmuVolGroup_t array. | ||
| resetVolGroups() | Clears the internal DmuVolGroup_t array. | ||
| toVolGroupsImage() | Converts a DmuVolGroups_t object to a DmuStringImage_t (defined in libdmfcom.H ) in the following format:
The delimiter between multiple vgname values may be a space, a tab, or a comma. | ||
| fromVolGroupsImage() | Converts a string image of the following format to a DmuVolGroups_t object:
The delimiter between multiple vgname values may be a space, a tab, or a comma. |
This section describes the following types of user-accessible API subroutines:
The DmuContext_t object manipulated by the DmuCreateContext(), DmuDestroyContext(), and DmuChangedDirectory() subroutines is designed to be completely opaque to the application. The context is used on all API subroutine calls so that the API can successfully manage user request and reply processing, but its internal contents are of no interest or use to the application.
You can use multiple DmuContext_t objects within the same process if desired.
The DmuCreateContext() subroutine creates an opaque context for the API to use to correctly communicate with the dmusrcmd process. This subroutine should be the first API subroutine called by a DMF user command. Not only is the context created, but the communication channel to the dmusrcmd process is initialized.
Normally, a context would be used for multiple requests and only destroyed when no more requests are to be made. Creating and destroying a context for each request is likely to be inefficient if done frequently.
The prototype is as follows:
extern DmuError_t
DmuCreateContext(
const char *prog_name,
DmuCreateFlags_t create_flags,
DmuSeverity_t severity,
DmuErrHandler_f err_handler,
DmuContext_t *dmuctxt,
pid_t *child_pid,
DmuAllErrors_t *errs) |
The parameters are as follows:
| prog_name | Contains the name of the program. This field can be the full pathname of the program or some other representation. | |||||
| create_flags | Specifies a DmuCreateFlags_t object (defined in libdmfusr.H) that specifies create options. The only valid create_flags option is:
| |||||
| severity | Specifies a DmuSeverity_t object that specifies the level of error reporting. See “DmuSeverity_t”. | |||||
| err_handler | Specifies a user-defined error handling subroutine. The DmuErrHandler_f object is defined in libdmfusr.H. If the err_handler parameter is NULL, the default error handler DmuDefErrHandler is used. For more information, see “DmuErrHandler_f”. | |||||
| dmuctxt | Specifies a DmuContext_t object (defined in libdmfusr.H) that is returned with the address of the newly created API to be used on all subsequent subroutine calls that require the program's API context. | |||||
| child_pid | Specifies the process ID (PID) of the child that is forked and executed to create the dmusrcmd process. This value is returned to the caller so that the caller is free to handle the termination of child signals as desired. | |||||
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t” . | |||||
If the DmuCreateContext call completes successfully, it returns DmuNoError.
The DmuChangedDirectory subroutine changes the current directory of the context. This subroutine is useful to a process that will be making multiple API file requests using relative pathnames while the process might also be making chdir(3) subroutine calls.
When a process makes a chdir call, if the DmuChangedDirectory() subroutine is called before the next API file request that references a relative pathname is made, the file reference will be successfully made by the process.
The prototype is as follows:
extern DmuError_t
DmuChangedDirectory(
const DmuContext_t dmuctxt,
const char *new_directory,
DmuAllErrors_t *errs); |
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| new_directory | Specifies a read-only character pointer to the string containing the directory path that was passed on the last chdir(3) subroutine call. | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
The DmuDestroyContext() subroutine destroys the API context dmuctxt. The memory that had been allocated for its use is freed.
The prototype is as follows:
extern DmuError_t
DmuDestroyContext(
DmuContext_t dmuctxt,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
Each of the following subroutines makes a DMF file request. The context parameter that is included in each of these subroutines must have been already initialized via DmuCreateContext.
The DmuCopyAsync() and DmuCopySync() subroutines perform copy requests in the manner of the dmcopy(1) command.
The DmuCopyAsync() subroutine returns immediately after the copy request has been forwarded to the dmusrcmd process. If a reply is desired, the caller must process the reply to this request. See “Request Completion Subroutines”.
The DmuCopySync() subroutine does not return until the requested copy has either completed successfully or been aborted due to an error condition.
The prototypes are as follows:
extern DmuError_t
DmuCopyAsync(
const DmuContext_t dmuctxt,
const char *srcfile_path,
const char *dstfile_path,
DmuCopyFlags_t copy_flags,
const DmuCopyRanges_t *copyranges,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuCopySync(
const DmuContext_t dmuctxt,
const char *srcfile_path,
const char *dstfile_path,
DmuCopyFlags_t copy_flags,
const DmuCopyRanges_t *copyranges,
DmuPriority_t priority,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| srcfile_path | Specifies the pathname of the source (input) file for the copy operation. It must be an offline or dual-state DMF file. | |
| dstfile_path | Specifies the pathname of the destination (output) file for the copy operation. This path must point to a file that exists or can be created in a DMF-managed filesystem that is native on the same host as that of the source file's filesystem. | |
| copy_flags | Specifies the OR'd value of the following copy operation flags as defined in libdmfcom.H:
| |
| copyranges | Specifies a pointer to a DmuCopyRanges_t object, as defined in “DmuCopyRanges_t” and in libdmfcom.H. This object can have only one DmuCopyRange_t as defined in “DmuCopyRange_t” and in libdmfcom.H. | |
| priority | Specifies a DmuPriority_t object (defined in libdmfcom.H) that defines the request priority. (Deferred implementation.) | |
| request_id | Specifies a pointer to a DmuReqid_t object (defined in libdmfcom.H) parameter that will be returned with the unique request ID of the asynchronous request. This value can be used when processing DmuCompletion_t objects (see “Request Completion Subroutines”). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If the subroutine succeeds, it returns DmuNoError.
The following subroutines send a fullstat request to the dmusrcmd process:
| DmuFullstatByFhandleAsync() |
| DmuFullstatByFhandleSync() |
| DmuFullstatByPathAsync() |
| DmuFullstatByPathSync() |
These subroutines have the following things in common:
The 'Sync' versions of these subroutines do not return until the DmuFullstat_t has been received or the request has been aborted due to errors.
The 'Async' versions of these subroutines return immediately after successfully forwarding the fullstat request to the dmusrcmd process. If a reply is desired, the caller must process the reply to this request. See “Request Completion Subroutines”. That is the only way to actually receive the DmuFullstat_t object for an 'Async' fullstat request, however. The DmuFullstatCompletion() subroutine has been supplied to extract the fullstat information from a fullstat completion object.
The 'ByPath' versions of these subroutines allow the target file to be defined by its pathname.
The 'ByFhandle' versions of these subroutines allow the target file to be defined by its filesystem handle, the fhandle. These subroutines are valid only when the command making the call is on the DMF server machine, and they are valid only when a user has sufficient (root) privileges.
These subroutines can return a successful completion ( DmuNoError), but might not return valid DmuFullstat_t information. The subroutines are designed to return the normal stat type information regardless of whether a DMAPI fullstat could be successfully completed. Upon return from these subroutines, the caller can use the DmuFullstat_t is_valid() member function to verify the validity of the DMAPI information in the DmuFullstat_t block.
The ultimate result of this request is the transfer of a DmuFullstat_t object to the caller.
The prototypes are as follows:
extern DmuError_t
DmuFullstatByFhandleAsync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuFullstatByFhandleSync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuFullstat_t *dmufullstat,
DmuAllErrors_t *errs)
extern DmuError_t
DmuFullstatByPathAsync(
const DmuContext_t dmuctxt,
const char *path,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuFullstatByPathSync(
const DmuContext_t dmuctxt,
const char *path,
DmuFullstat_t *dmufullstat,
DmuFhandle_t *fhandle,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| client_fhandle | Specifies the DMF filesystem fhandle of the target file. Valid for use only by a privileged (root ) user on the DMF server machine. | |
| path | Specifies the relative or absolute pathname of the target file. | |
| dmufullstat | Specifies the pointer that will be returned with the DmuFullstat_t object. | |
| fhandle | Specifies the pointer that will be returned with the DmuFhandle_t value. | |
| request_id | Specifies a pointer to a DmuReqid_t object (defined in libdmfcom.H) parameter that will be returned with the unique request ID of the asynchronous request. This value can be used when processing DmuCompletion_t objects (see “Request Completion Subroutines”). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If the subroutine succeeds, it returns DmuNoError.
The following subroutines perform the put DMF request:
| DmuPutByFhandleAsync() |
| DmuPutByFhandleSync() |
| DmuPutByPathAsync() |
| DmuPutByPathSync() |
These subroutines have the following things in common:
The 'Sync' versions do not return until the put request has either completed successfully, or been aborted due to errors.
The 'Async' versions return immediately after successfully forwarding the put request to the dmusrcmd process. If a reply is desired, the caller must process the reply to this request. See “Request Completion Subroutines”.
The 'ByPath' versions allow the target file to be defined by its pathname.
The 'ByFhandle' versions allow the target file to be defined by its filesystem handle, the fhandle . These subroutines are valid only when the command making the call is on the DMF server machine, and they are valid only when a user has sufficient (root) privileges.
The prototypes are as follows:
extern DmuError_t
DmuPutByFhandleAsync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuMigFlags_t mig_flags,
const DmuByteRanges_t *byteranges,
const DmuVolGroups_t *volgroups,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuPutByFhandleSync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuMigFlags_t mig_flags,
const DmuByteRanges_t *byteranges,
const DmuVolGroups_t *volgroups,
DmuPriority_t priority,
DmuAllErrors_t *errs)
extern DmuError_t
DmuPutByPathAsync(
const DmuContext_t dmuctxt,
const char *path,
DmuMigFlags_t mig_flags,
const DmuByteRanges_t *byteranges,
const DmuVolGroups_t *volgroups,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuPutByPathSync(
const DmuContext_t dmuctxt,
const char *path,
DmuMigFlags_t mig_flags,
const DmuByteRanges_t *byteranges,
const DmuVolGroups_t *volgroups,
DmuPriority_t priority,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| client_fhandle | Specifies the DMF filesystem fhandle of the target file. Valid for use only by a privileged (root ) user on the DMF server machine. | |
| path | Specifies the relative or full pathname of the target file. | |
| mig_flags | Specifies the following migration flags as defined in libdmfcom.H:
| |
| byteranges | Specifies a pointer to a DmuByteRanges_t object. See “DmuByteRanges_t”. | |
| volgroups | Specifies a pointer to a DmuVolGroups_t object. See “DmuVolGroups_t”. | |
| priority | Specifies a DmuPriority_t object (defined in libdmfcom.H) that defines the request priority. (Deferred implementation.) | |
| request_id | Specifies a pointer to a DmuReqid_t object (defined in libdmfcom.H) parameter that will be returned with the unique request ID of the asynchronous request. This value can be used when processing DmuCompletion_t objects (see “Request Completion Subroutines”). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If the subroutine succeeds, it returns DmuNoError.
The following subroutines perform the get DMF request:
| DmuGetByFhandleAsync() |
| DmuGetByFhandleSync() |
| DmuGetByPathAsync() |
| DmuGetByPathSync() |
These subroutines have the following things in common:
The 'Sync' versions do not return until the get request has either completed successfully or has been aborted due to errors.
The 'Async' versions return immediately after successfully forwarding the get request to the dmusrcmd process. If a reply is desired, the caller must process the reply to this request. See “Request Completion Subroutines”.
The 'ByPath' versions of these calls allow the target file to be defined by its pathname.
The 'ByFhandle' versions allow the target file to be defined by its filesystem handle, the fhandle . These subroutines are valid only when the command making the call is on the DMF server machine, and they are valid only when a user has sufficient (root) privileges.
The prototypes are as follows:
extern DmuError_t
DmuGetByFhandleAsync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuRecallFlags_t recall_flags,
const DmuByteRanges_t *byteranges,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuGetByFhandleSync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuRecallFlags_t recall_flags,
const DmuByteRanges_t *byteranges,
DmuPriority_t priority,
DmuAllErrors_t *errs)
extern DmuError_t
DmuGetByPathAsync(
const DmuContext_t dmuctxt,
const char *path,
DmuRecallFlags_t recall_flags,
const DmuByteRanges_t *byteranges,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuGetByPathSync(
const DmuContext_t dmuctxt,
const char *path,
DmuRecallFlags_t recall_flags,
const DmuByteRanges_t *byteranges,
DmuPriority_t priority,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| client_fhandle | Specifies the DMF filesystem fhandle of the target file. Valid for use only by a privileged (root ) user on the DMF server machine. | |
| path | Specifies the relative or full pathname of the target file. | |
| recall_flags | Specifies the following recall flags as defined in libdmfcom.H:
| |
| byteranges | Specifies a pointer to a DmuByteRanges_t object. See “DmuByteRanges_t”. | |
| priority | Specifies a DmuPriority_t object (defined in libdmfcom.H) that defines the request priority. (Deferred implementation.) | |
| request_id | Specifies a pointer to a DmuReqid_t (defined in libdmfcom.H) parameter that will be returned with the unique request ID of the asynchronous request. This value can be used when processing DmuCompletion_t objects (see “Request Completion Subroutines”). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If the subroutine succeeds, it returns DmuNoError.
The settag request performs the same functional task as the dmtag (1) command. The following subroutines perform the settag DMF request:
| DmuSettagByFhandleAsync() |
| DmuSettagByFhandleSync() |
| DmuSettagByPathAsync() |
| DmuSettagByPathSync() |
These subroutines have the following things in common:
The 'Sync' versions do not return until the settag request has either completed successfully or has been aborted due to errors.
The 'Async' versions return immediately after successfully forwarding the settag request to the dmusrcmd process. If a reply is desired, the caller must process the reply to this request. See “Request Completion Subroutines”.
The 'ByPath' versions allow the target file to be defined by its pathname.
The 'ByFhandle' versions allow the target file to be defined by its filesystem handle, the fhandle . These subroutines are valid only when the command making the call is on the DMF server machine and when a user has sufficient ( root) privileges.
The prototypes are as follows:
extern DmuError_t
DmuSettagByFhandleAsync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuSettagFlags_t settag_flags,
DmuSitetag_t sitetag,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuSettagByFhandleSync(
const DmuContext_t dmuctxt,
const DmuFhandle_t *client_fhandle,
DmuSettagFlags_t settag_flags,
DmuSitetag_t sitetag,
DmuPriority_t priority,
DmuAllErrors_t *errs)
extern DmuError_t
DmuSettagByPathAsync(
const DmuContext_t dmuctxt,
const char *path,
DmuSettagFlags_t settag_flags,
DmuSitetag_t sitetag,
DmuPriority_t priority,
DmuReqid_t *request_id,
DmuAllErrors_t *errs)
extern DmuError_t
DmuSettagByPathSync(
const DmuContext_t dmuctxt,
const char *path,
DmuSettagFlags_t settag_flags,
DmuSitetag_t sitetag,
DmuPriority_t priority,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| client_fhandle | Specifies the DMF filesystem fhandle of the target file. Valid for use only by a privileged (root ) user on the DMF server machine. | |
| path | Specifies the relative or full pathname of the target file. | |
| settag_flags | Specifies the following settag flags as defined in libdmfcom.H:
| |
| sitetag | Defines the file site tag value. See dmtag(1). | |
| priority | Specifies a DmuPriority_t object (defined in libdmfcom.H) that defines the request priority. (Deferred implementation.) | |
| request_id | Specifies a pointer to a DmuReqid_t (defined in libdmfcom.H) parameter that will be returned with the unique request ID of the asynchronous request. This value can be used when processing DmuCompletion_t objects (see “Request Completion Subroutines”). | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If the subroutine succeeds, it returns DmuNoError.
The request completion subroutines are provided so that the application can process the completion events of any asynchronous requests it might have issued. The caller can choose to process each request's completion object (DmuCompletion_t ) or to be notified when each request has responded with either an intermediate or final (completion) reply.
The asynchronous requests described previously along with the following completion subroutines allow the user to achieve maximum parallelization of the processing of all requests.
The DmuAwaitReplies() subroutine performs a synchronous wait until the number of outstanding request replies of the type specified is less than or equal to max_outstanding . This subroutine is called by a user who does not want to perform individual processing of each outstanding request, but wants to know when a reply (intermediate or final) has been received for each request that has been sent to this point.
The prototype is as follows:
extern DmuError_t
DmuAwaitReplies(
const DmuContext_t dmuctxt,
DmuReplyType_t type,
int max_outstanding,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |
| type | Defines the type of reply to be received. The caller can wait for an intermediate or final reply for the outstanding requests. See the definition of DmuReplyType_t in “DmuReplyType_t” or in libdmfcom.H. | |
| max_outstanding | Specifies the number of outstanding requests allowed for which the type reply has not been received before the subroutine returns. If this parameter is 0, all type replies will have been received when the subroutine returns. | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
If no errors occurred getting the next reply, this subroutine returns DmuNoError.
The DmuFullstatCompletion() subroutine can be called when asynchronous fullstat replies are being processed by DmuGetNextReply() or DmuGetThisReply() . When the reply is received, the DmuCompletion_t object that is part of the reply can be used as an input parameter to this routine, which will then extract the DmuFullstat_t object and the DmuFhandle_t objects that are contained in the DmuCompletion_t object's ureq_data field.
The prototype is as follows:
extern DmuError_t
DmuFullstatCompletion(
DmuCompletion_t *comp;
DmuFullstat_t *dmufullstat,
DmuFhandle_t *fhandle,
DmuAllErrors_t *errs) |
The parameters are as follows:
| comp | Specifies the DmuCompletion_t object from an asynchronous fullstat request. | |
| dmufullstat | Specifies a pointer to an existing DmuFullstat_t object. If comp references a successful fullstat request, dmufullstat will be set to be equal to the DmuFullstat_t that was returned with the reply. | |
| fhandle | Specifies a pointer to an existing DmuFhandle_t object. If comp references a successful fullstat request, fhandle will be set to be equal to the DmuFhandle_t that was returned with the reply. | |
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”. |
The DmuGetNextReply() subroutine returns the completion object of the next reply based on the order specified on the call.
The caller can specify DmuIntermed or DmuFinal for the type parameter. If DmuIntermed is specified and an intermediate reply is the next reply received and there are no completed replies available for processing, the comp parameter is not set (will be NULL ) when the subroutine returns. An intermediate reply has no completion object associated with it; a return of this type is informational only.
This subroutine performs a synchronous wait until a request reply of the type specified on the call is received. At the time of the call, any reply that has already been received and is queued for processing is returned immediately.
The prototype is as follows:
extern DmuError_t
DmuGetNextReply(
const DmuContext_t dmuctxt,
DmuReplyOrder_t order,
DmuReplyType_t type,
DmuCompletion_t *comp,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |||
| order | Defines the order in which the request replies should be returned. The caller can process the replies in the order the replies are received (DmuAnyOrder) or in the order the requests were issued (DmuReqOrder). See the definition of DmuReplyOrder_t in “DmuReplyOrder_t” or in libdmfcom.H. | |||
| type | Defines the type of reply to be received. The caller can wait for an intermediate or final reply for the outstanding requests. The receipt of an intermediate reply returns no data. | |||
| comp | Specifies a pointer to an existing DmuCompletion_t object. If a reply was available for processing according to the parameters on the calling subroutine, the DmuCompletion_t object pointed to by comp will be set with all of the appropriate values. See “DmuCompletion_t”. If the reply_code field of the comp parameter is not DmuNoError, the comp->allerrors object will contain the error information needed to determine the cause of the error.
| |||
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t”.
|
If no errors occurred getting the next reply, this subroutine returns DmuNoError. If there are no outstanding requests pending, a return code of DME_DMU_QUEUEEMPTY is returned. You can use a check for DME_DMU_QUEUEEMPTY to terminate a while loop based on this subroutine. Any other error return code indicates an error, and the errs parameter can be processed for the error information.
The DmuGetThisReply() subroutine returns the completion object of the specified request. This subroutine performs a synchronous wait until a request reply specified on the call is received.
The prototype is as follows:
extern DmuError_t
DmuGetThisReply(
const DmuContext_t dmuctxt,
DmuReqid_t request_id,
DmuCompletion_t *comp,
DmuAllErrors_t *errs) |
The parameters are as follows:
| dmuctxt | Specifies a DmuContext_t object that was previously created by DmuCreateContext(). | |||
| request_id | Specifies the unique request ID of the request for which the caller wants to wait. | |||
| comp | Specifies a pointer to an existing DmuCompletion_t object. If a reply was available for processing according to the parameters on the calling subroutine, the DmuCompletion_t object pointed to by comp will be set with all of the appropriate values. See “DmuCompletion_t”. The reply_code field of the comp parameter is the ultimate status of the request. A successful comp has a reply_code of DmuNoError . If the reply_code of comp is not DmNoError, the comp->allerrors object will contain the error information needed to determine the cause of the error.
| |||
| errs | Specifies a pointer to a DmuAllErrors_t object. This value may be NULL. If it is not NULL, the subroutine will use it to return errors. See “DmuAllErrors_t” .
|
If no errors occurred getting the next reply, this subroutine returns DmuNoError. Any other error return code indicates an error, and the errs parameter can be processed for the error information.