--- name: "globus_gass_cache" section: "3" platform: "linux" package: "libglobus-gass-cache-doc" version: "10.3-3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/globus_gass_cache" --- # globus\_gass\_cache(3) Globus GASS Cache - Globus GASS Cache. ## NAME globus\_gass\_cache - Globus GASS Cache \- Globus GASS Cache. ## SYNOPSIS ### Macros \#define **GLOBUS\_GASS\_CACHE\_MODULE** (&globus\_i\_gass\_cache\_module)\ module\_descriptor ### Typedefs typedef struct globus\_i\_gass\_cache\_t \* **globus\_gass\_cache\_t**\ GASS Cache Handle. ### Functions int **globus\_gass\_cache\_open** (const char \*cache\_directory\_path, **globus\_gass\_cache\_t** \*cache\_handlep)\ Open a GASS Cache. int **globus\_gass\_cache\_close** (**globus\_gass\_cache\_t** \*cache\_handlep)\ Close a cache handle. int **globus\_gass\_cache\_add** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, globus\_bool\_t create, unsigned long \*timestamp, char \*\*local\_filename)\ Add a tag to an URL in the cache. int **globus\_gass\_cache\_add\_done** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, unsigned long timestamp)\ Complete adding a cache entry and unlock it. int **globus\_gass\_cache\_query** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, globus\_bool\_t wait\_for\_lock, unsigned long \*timestamp, char \*\*local\_filename, globus\_bool\_t \*is\_locked)\ Query the GASS Cache. int **globus\_gass\_cache\_delete\_start** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, unsigned long \*timestamp)\ Remove a cache tag. int **globus\_gass\_cache\_delete** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, unsigned long timestamp, globus\_bool\_t is\_locked)\ Remove one instance of the tag from the cache entry's tag list. int **globus\_gass\_cache\_cleanup\_tag** (**globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag)\ Remove a tag from a cache entry. int **globus\_gass\_cache\_cleanup\_tag\_all** (**globus\_gass\_cache\_t** cache\_handle, char \*tag)\ Remove a tag from all cache entries Remove all instances of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file. If the cache entry is locked with the same tag as is passed to this function, then the entry is unlocked after removing the tags. Otherwise, the cache entry's lock is left untouched. " int **globus\_gass\_cache\_mangle\_url** (const **globus\_gass\_cache\_t** cache\_handle, const char \*url, char \*\*mangled\_url, int \*length)\ Convert a URL to a string suitable as a file path. int **globus\_gass\_cache\_mangle\_tag** (const **globus\_gass\_cache\_t** cache\_handle, const char \*tag, char \*\*mangled\_tag, int \*length)\ Convert a tag to a string suitable as a file path. int **globus\_gass\_cache\_get\_cache\_dir** (const **globus\_gass\_cache\_t** cache\_handle, char \*\*cache\_dir)\ Get the GASS Cache's root directory. int **globus\_gass\_cache\_get\_dirs** (const **globus\_gass\_cache\_t** cache\_handle, const char \*url, const char \*tag, char \*\*global\_root, char \*\*local\_root, char \*\*tmp\_root, char \*\*log\_root, char \*\*global\_dir, char \*\*local\_dir)\ Get the set of directories used by a GASS Cache. int **globus\_gass\_cache\_get\_cache\_type\_string** (const **globus\_gass\_cache\_t** cache\_handle, char \*\*cache\_type)\ Get the type of GASS Cache directory layout. const char \* **globus\_gass\_cache\_error\_string** (int error\_code)\ Look up the error string corresponding to a GASS Cache error. ## Detailed Description Globus GASS Cache. The GASS cache management API is part of the Globus module called 'GASS', (Global Access to Secondary Storage) The GASS cache management API defines calls for manipulating a local file cache. \ Each cache entry can be locked during addition and deletion to allow for atomic handling of the cache file contents. Each cache entry also has an associated timestamp. This timestamp is independent of the local cache file's modification time. Rather, the cache entry timestamp is maintained by the user. It can, for example, be used to keep track of the timestamp of a remote file that is associated with the cache entry. Note: all timestamps are as seconds since the epoch. (01 Jan 1970, 00:00 GMT) The following functions are part of the API: - • **globus\_gass\_cache\_open()** - • **globus\_gass\_cache\_close()** - • **globus\_gass\_cache\_add()** - • **globus\_gass\_cache\_add\_done()** - • **globus\_gass\_cache\_delete\_start()** - • **globus\_gass\_cache\_delete()** - • **globus\_gass\_cache\_cleanup\_tag()** - • **globus\_gass\_cache\_cleanup\_tag\_all()** - • **globus\_gass\_cache\_mangle\_url()** - • **globus\_gass\_cache\_mangle\_tag()** - • **globus\_gass\_cache\_get\_dirs()** - • **globus\_gass\_cache\_get\_cache\_dir()** ## Typedef Documentation ### typedef struct globus\_i\_gass\_cache\_t\* globus\_gass\_cache\_t GASS Cache Handle. Data structure used to store information concerning an open cache directory. This structure MUST NOT be modified directly, but passed to the globus\_gass\_cache functions ## Function Documentation ### int globus\_gass\_cache\_add (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, globus\_bool\_t create, unsigned long \* timestamp, char \*\* local\_filename)` [extern]` Add a tag to an URL in the cache. Create a new cache file or add a tag on it. If the URL is already in the cache but is locked, then this call will block until the cache entry is unlocked, then will proceed with the subsequent operations. If the URL is already in the cache and unlocked, then add the tag to the cache entry's tag list, return the local cache filename in \*local\_filename, return the entry's current timestamp in \*timestamp, lock the cache entry, and return GLOBUS\_GASS\_CACHE\_ADD\_EXISTS. If the URL is not in the cache, and create==GLOBUS\_TRUE, then create a new unique empty local cache file, add it to the cache with the specified tag, return the filename in \*local\_filename, return \*timestamp set to GLOBUS\_GASS\_CACHE\_TIMESTAMP\_UNKNOWN, lock the cache entry, and return GLOBUS\_GASS\_CACHE\_ADD\_NEW. If the URL is not in the cache, and create==GLOBUS\_FALSE, then do not add it to the cache, and return GLOBUS\_GASS\_CACHE\_URL\_NOT\_FOUND. If this function returns GLOBUS\_GASS\_CACHE\_ADD\_EXISTS or GLOBUS\_GASS\_CACHE\_ADD\_NEW, then **globus\_gass\_cache\_add\_done()** or **globus\_gass\_cache\_delete()** must be subsequently called to unlock the cache entry. Subsequent calls to **globus\_gass\_cache\_add()** and **globus\_gass\_cache\_delete\_start()** on the same cache and url, made either from this process or another, will block until the cache entry is unlocked. If tag==NULL, then a tag with the value 'null' will be added to the cache entry's tag list. The same tag can be used multiple times, in which case this tag will be added to the entry's tag list multiple times. Note: It is recommended that proglobus\_grams started via GLOBUS\_GRAM pass a tag value of getenv('GLOBUS\_GRAM\_JOB\_CONTACT'), since upon completion of a job GLOBUS\_GRAM will automatically cleanup entries with this tag. **Note** the local\_filename MUST be free by the user in a subsequent operation, using free() **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* URL of the file to be cached. It is used as the main key to the cache entries. \ *tag* Tag specifying which job is/are using the cache. This is usually the GLOBUS\_GRAM\_JOB\_CONTACT. Can be NULL or empty; the tag 'null' is then used. create - Tells if the cache entry should be created if it is not already existing. \ *create* Flag to create if it does not already exist. \ *timestamp* Timestamp of the cached file, set by globus\_gass\_cache\_done(), (or **globus\_gass\_cache\_delete()** ). \ *local\_filename* Path the the local file caching the file specified by 'url'. NULL if 'url' not yet cached and creation not requested (create false). **Returns** - • GLOBUS\_GASS\_CACHE\_URL\_NOT\_FOUND - • GLOBUS\_GASS\_CACHE\_ADD\_NEW - • GLOBUS\_GASS\_CACHE\_ADD\_EXISTS - • or any of the defined gass error code. ### int globus\_gass\_cache\_add\_done (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, unsigned long timestamp)` [extern]` Complete adding a cache entry and unlock it. **globus\_gass\_cache\_add\_done()** MUST be called after **globus\_gass\_cache\_add()**, to set the timestamp in the cache entry for the URL, and then unlock the cache entry. (The only case it does not need to be called is if **globus\_gass\_cache\_add()** has returned GLOBUS\_GASS\_CACHE\_URL\_NOT\_FOUND, of course. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* URL of the cached file to set as 'done' (unlock) \ *tag* Tag specifying which job has locked the cache and must therefore be unlocked. It is an error to call this function with a tag which does not currently own the cache lock. \ *timestamp* Timestamp of the cached file. **Returns** **globus\_gass\_cache\_add\_done()** returns GLOBUS\_SUCCESS or any of the defined GASS Cache error codes. ### int globus\_gass\_cache\_cleanup\_tag (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag)` [extern]` Remove a tag from a cache entry. Remove all instances of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file. If the cache entry is locked with the same tag as is passed to this function, then the entry is unlocked after removing the tags. Otherwise, the cache entry's lock is left untouched. This function does not block on a locked reference. **Note** The GLOBUS\_GRAM job manager will automatically call this function with a tag of getenv('GLOBUS\_GRAM\_JOB\_CONTACT') upon completion of a job. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* URL of the file to be cached. It is used as the main key to the cache entries. \ *tag* Tag specifying which job is/are using the cache. This is usually the GLOBUS\_GRAM\_JOB\_CONTACT. Can be NULL or empty; the tag 'null' is then used. **Returns** The **globus\_gass\_cache\_cleanup\_tag()** function returns GLOBUS\_SUCCESS or any of the defined GASS Cache error codes. \ ### int globus\_gass\_cache\_cleanup\_tag\_all (globus\_gass\_cache\_t cache\_handle, char \* tag)` [extern]` Remove a tag from all cache entries Remove all instances of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file. If the cache entry is locked with the same tag as is passed to this function, then the entry is unlocked after removing the tags. Otherwise, the cache entry's lock is left untouched. This function does not block on a locked reference. This function differs from **globus\_gass\_cache\_cleanup\_tag()** in that this cleans up **all** URLs related with this tag. **Note** The GLOBUS\_GRAM job manager will automatically call this function with a tag of getenv('GLOBUS\_GRAM\_JOB\_CONTACT') upon completion of a job. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *tag* Tag specifying which job is/are using the cache. This is usually the GLOBUS\_GRAM\_JOB\_CONTACT. Can be NULL or empty; the tag 'null' is then used. **Returns** The **globus\_gass\_cache\_cleanup\_tag\_all()** function returns GLOBUS\_SUCCESS or any of the defined GASS Cache error codes. ### int globus\_gass\_cache\_close (globus\_gass\_cache\_t \* cache\_handlep) Close a cache handle. Close (NOT delete) a previously opened cache: - • close the opened files and - • free the memory allocated for the cache\_handle. - • mark the handle as 'not initialized'. Parameters: cache\_handle: Handle to the opened cache directory to use. \ cache\_handle-\>is\_init set to 'not initialized' and all the files opened bu globus\_gass\_cache\_open are closed . Returns: GLOBUS\_SUCCESS or error code: GLOBUS\_GASS\_CACHE\_ERROR\_CACHE\_NOT\_OPENED ### int globus\_gass\_cache\_delete (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, unsigned long timestamp, globus\_bool\_t is\_locked)` [extern]` Remove one instance of the tag from the cache entry's tag list. If there are no more tags in the tag list, then remove this cache entry and delete the associated local cache file. Otherwise, update the timestamp to the passed value. This call will leave the cache entry unlocked. If is\_locked==GLOBUS\_TRUE, then this cache entry was locked during a previous call to **globus\_gass\_cache\_add()** or **globus\_gass\_cache\_delete\_start()**. The cache file should be locked by the corresponding url/tag, or an error is returned. If it is locked by the corresponding url/tag, then the normal operation occur, without blocking (remove one instance from the tag update the timestamp and unlock the cache). If is\_locked==GLOBUS\_FALSE, eventually wait the cache is not locked any more, and then proceed with the normal operations.(remove one instance from the tag list and update the timestamp). **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* URL of the file to be cached. It is used as the main key to the cache entries. \ *tag* Tag specifying which job is/are using the cache. This is usually the GLOBUS\_GRAM\_JOB\_CONTACT. Can be NULL or empty; the tag 'null' is then used. \ *timestamp* Timestamp of the cached file. \ *is\_locked* Indicate if this cache entry was locked during a previous call to **globus\_gass\_cache\_add()** or **globus\_gass\_cache\_delete\_start()**. **Returns** The **globus\_gass\_cache\_delete()** function returns GLOBUS\_SUCCESS or any of the defined GASS Cache error codes. ### int globus\_gass\_cache\_delete\_start (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, unsigned long \* timestamp)` [extern]` Remove a cache tag. Lock the cache entry for the URL, and return the cache entry's current timestamp in \*timestamp. This function will block if the data file is already locked, until it is unlocked. **Parameters** *cache\_handle* Handle to the opened cache directory to use.\ *url* URL of the cached file to set as 'done' (unlock) \ *tag* Tag specifying which job has locked the cache and must therefore be unlocked. It is an error to call this function with a tag which does not currently own the cache lock. \ *timestamp* Timestamp of the cached file, set by globus\_gass\_cache\_done(), (or **globus\_gass\_cache\_delete()** ). **Returns** The **globus\_gass\_cache\_delete\_start()** function returns GLOBUS\_SUCCESS or any of the defined GASS Cache error code. ### const char \* globus\_gass\_cache\_error\_string (int error\_code)` [extern]` Look up the error string corresponding to a GASS Cache error. Return a pointer on an error description string. **Parameters** *error\_code* error code returned by a previously called globus\_gass\_cache function. **Returns** The **globus\_gass\_cache\_error\_string()** function returns a pointer to an error message, or NULL if error\_code is invalid. ### int globus\_gass\_cache\_get\_cache\_dir (const globus\_gass\_cache\_t cache\_handle, char \*\* cache\_dir)` [extern]` Get the GASS Cache's root directory. Get a the root cache of directory. This is exported for use in the globus\_gass\_cache program. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *cache\_dir* Pointer to the cache directory **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_MEMORY* No memory ### int globus\_gass\_cache\_get\_cache\_type\_string (const globus\_gass\_cache\_t cache\_handle, char \*\* cache\_type)` [extern]` Get the type of GASS Cache directory layout. Get a string which describes the cache type ('normal' or 'flat') **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *cache\_type* Pointer to the strdup()ed string **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_MEMORY* No memory ### int globus\_gass\_cache\_get\_dirs (const globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, char \*\* global\_root, char \*\* local\_root, char \*\* tmp\_root, char \*\* log\_root, char \*\* global\_dir, char \*\* local\_dir)` [extern]` Get the set of directories used by a GASS Cache. Gets a bunch of directories. This is exported for use in the globus\_gass\_cache program. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* The incoming URL \ *tag* The incoming tag \ *local\_root* Pointer to the 'local root' directory \ *global\_root* Pointer to the 'global root' directory \ *tmp\_root* Pointer to the 'tmp root' directory \ *log\_root* Pointer to the root log directory \ *local\_dir* Pointer to the related 'local' directory \ *global\_dir* Pointer to the related 'global' directory **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_MEMORY* No memory ### int globus\_gass\_cache\_mangle\_tag (const globus\_gass\_cache\_t cache\_handle, const char \* tag, char \*\* mangled\_tag, int \* length)` [extern]` Convert a tag to a string suitable as a file path. Mangles the given tag into a chunk suitable for using as a file / path name. This is exported for use in the globus\_gass\_cache program. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *tag* The incoming tag to mangle (NULL-terminated) \ *mangled\_tag* Pointer to the output string; a buffer for the real string is malloc()ed for the application. If mangled is NULL, then no such buffer is allocated, and no mangled string is created. This can be useful to just get the length of the mangled string. \ *length* A pointer to the length of the resulting string. If NULL, this is not assigned to. **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_MEMORY* No memory ### int globus\_gass\_cache\_mangle\_url (const globus\_gass\_cache\_t cache\_handle, const char \* url, char \*\* mangled\_url, int \* length)` [extern]` Convert a URL to a string suitable as a file path. Mangles the given URL into a chunk suitable for using as a file / path name. This is exported for use in the globus\_gass\_cache program. **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* The incoming URL to mangle (NULL-terminated) \ *mangled\_url* Pointer to the output string; a buffer for the real string is malloc()ed for the application. If mangled is NULL, then no such buffer is allocated, and no mangled string is created. This can be useful to just get the length of the mangled string. \ *length* A pointer to the length of the resulting string. If NULL, this is not assigned to. **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_MEMORY* No memory ### int globus\_gass\_cache\_open (const char \* cache\_directory\_path, globus\_gass\_cache\_t \* cache\_handlep) Open a GASS Cache. Open the cache specified by the cache\_directory\_path argument, and return a cache handle that can be used in subsequent cache calls. If cache\_directory\_path is NULL, then use the value contained in the GLOBUS\_GASS\_CACHE\_DEFAULT environment variable if it is defined, otherwise use ~/.globus\_gass\_cache. The cache\_directory\_path must be a directory. If it is a file, this call will fail with a non-0 return value. If the specified directory does not exist, then this call will create the directory. **Parameters** *cache\_directory\_path* Path to the cache directory to open. Can be NULL (see above) \ *cache\_handlep* Structure containning all the necessary information to access the cache (file names, descriptor,...) (see globus\_gass\_gache.h) Some files are also opened: **globus\_gass\_cache\_close()** must be called subsequently to close those files. This parameter is modified by the **globus\_gass\_cache\_open()** **Return values** *GLOBUS\_SUCCESS* Success \ *GLOBUS\_GASS\_CACHE\_ERROR\_CACHE\_ALREADY\_OPENED* Handle already opened \ *GLOBUS\_GASS\_CACHE\_ERROR\_NAME\_TOO\_LONG* Path name too long \ *GLOBUS\_GASS\_CACHE\_ERROR\_NO\_HOME* Can't find home directory for default cache path ### int globus\_gass\_cache\_query (globus\_gass\_cache\_t cache\_handle, const char \* url, const char \* tag, globus\_bool\_t wait\_for\_lock, unsigned long \* timestamp, char \*\* local\_filename, globus\_bool\_t \* is\_locked)` [extern]` Query the GASS Cache. Query if an item is in the cache This call will block only if wait\_for\_lock is GLOBUS\_TRUE **Parameters** *cache\_handle* Handle to the opened cache directory to use. \ *url* URL of the file to query. It is used as the main key to the cache entries. \ *tag* Tag specifying which job is/are using the cache. This is usually the GLOBUS\_GRAM\_JOB\_CONTACT. Can be NULL or empty; the tag 'null' is then used. \ *wait\_for\_lock* If GLOBUS\_TRUE, wait for any lock existing lock to be released. If GLOBUS\_FALSE, doesn't wait for a lock to be released. \ *timestamp* Timestamp of the cached file, set by globus\_gass\_cache\_done(), (or **globus\_gass\_cache\_delete()** ). \ *local\_filename* Path the the local file caching the file specified by 'url'. NULL if 'url' not yet cached and creation not requested (create false). \ *is\_locked* GLOBUS\_TRUE if the file is currently (at return time) locked. **Returns** The **globus\_gass\_cache\_query()** function returns GLOBUS\_SUCCESS, GLOBUS\_GASS\_CACHE\_URL\_NOT\_FOUND, or any of the defined gass error code. ## Author Generated automatically by Doxygen for globus\_gass\_cache from the source code.