Content-type: text/html Manpage of GFAL

GFAL

Section: Library Functions (3)
Updated: 2003/12/17 08:33:47
Index Return to Main Contents
 

NAME

gfal - Grid File Access Library  

DESCRIPTION

Grid storage interactions today require using several existing software components:
.
The replica catalog services to locate valid replicas of files.
.
The SRM software to ensure:
.
files exist on disk (they are recalled from mass storage if necessary) or
.
space is allocated on disk for new files (they are possibly migrated to mass storage later)
.
A file access mechanism to access files from the storage system on the worker node.

The GFAL library hides these interactions and presents a Posix interface for the I/O operations. The currently supported protocols are: file for local access, dcap (dCache access protocol) and rfio (CASTOR access protocol).

The function names are obtained by prepending gfal_ to the Posix names, for example gfal_open, gfal_read, gfal_close ...

The argument lists and the values returned by the functions are identical.

File naming convention
A file name can be a Logical File Name (LFN), a Grid Unique IDentifier (GUID), a file replica (SURL) or a Transport file name (TURL).

an LFN starts with lfn:

for example lfn:baud/testgfal15

a GUID starts with guid:

for example guid:2cd59291-7ae7-4778-af6d-b1f423719441

an SURL starts with srm://

for example srm://wacdr002d.cern.ch:8443/castor/cern.ch/user/b/baud/testgfal15

a TURL starts with a protocol name

for example rfio:////castor/cern.ch/user/b/baud/testgfal15
Compile and link
The header file gfal_api.h needs to be included in the application source code to get the prototype of the functions. The application must be linked with libgfal (a few auxiliary security libraries: libcgsi_plugin_gsoap_2.3, libglobus_gssapi_gsi_gcc32dbg and libglobus_gss_assist_gcc32dbg are used internally).

All these libraries are available as shared libraries as well as archive libraries.

Replica Catalogs endpoints
To be able to use an LFN or a GUID as filename, one must specify the Virtual Organization LCG_GFAL_VO and the LCG_GFAL_INFOSYS or the servers endpoints, for example:

       setenv LCG_GFAL_VO dteam

       setenv LCG_GFAL_INFOSYS tbed0150.cern.ch:2170

or
       setenv RMC_ENDPOINT \

       http://rlscert01.cern.ch:7777/dteam/edg-replica-metadata-catalog/services/edg-replica-metadata-catalog

       setenv LRC_ENDPOINT \

       http://rlscert01.cern.ch:7777/dteam/edg-local-replica-catalog/services/edg-local-replica-catalog

Security
The SRMs can only be accessed in secure mode, i.e. require a valid Grid certificate and valid Grid proxy obtained by grid-proxy-init. The Replica catalogs can be accessed in secure or insecure mode depending on the endpoint provided: if it starts with https: the secure mode is used.
 

RETURN VALUE

The variable errno is set to the Posix error codes in the case of failure.  

EXAMPLES

A program writing a file, reading it back and checking the content of the file is shown below: 
#include <fcntl.h>
#include <stdio.h>
#include "gfal_api.h"
#define BLKLEN 65536

main(int argc, char **argv)
{
        int fd;
        int i;
        char ibuf[BLKLEN];
        char obuf[BLKLEN];
        int rc;

        if (argc != 2) {
                fprintf (stderr, "usage: %s filename\n", argv[0]);
                exit (1);
        }

        for (i = 0; i < BLKLEN; i++)
                obuf[i] = i;

        printf ("creating file %s\n", argv[1]);
        if ((fd = gfal_open (argv[1], O_WRONLY|O_CREAT, 0644)) < 0) {
                perror ("gfal_open");
                exit (1);
        }
        printf ("open successful, fd = %d\n", fd);

        if ((rc = gfal_write (fd, obuf, BLKLEN)) != BLKLEN) {
                if (rc < 0)
                        perror ("gfal_write");
                else
                        fprintf (stderr, "gfal_write returns %d\n", rc);
                (void) gfal_close (fd);
                exit (1);
        }
        printf ("write successful\n");

        if ((rc = gfal_close (fd)) < 0) {
                perror ("gfal_close");
                exit (1);
        }
        printf ("close successful\n");

        printf ("reading back %s\n", argv[1]);
        if ((fd = gfal_open (argv[1], O_RDONLY, 0)) < 0) {
                perror ("gfal_open");
                exit (1);
        }
        printf ("open successful, fd = %d\n", fd);

        if ((rc = gfal_read (fd, ibuf, BLKLEN)) != BLKLEN) {
                if (rc < 0)
                        perror ("gfal_read");
                else
                        fprintf (stderr, "gfal_read returns %d\n", rc);
                (void) gfal_close (fd);
                exit (1);
        }
        printf ("read successful\n");

        if ((rc = gfal_close (fd)) < 0) {
                perror ("gfal_close");
                exit (1);
        }
        printf ("close successful\n");

        for (i = 0; i < BLKLEN; i++) {
                if (ibuf[i] != obuf[i]) {
                        fprintf (stderr, "compare failed at offset %d\n", i);
                        exit (1);
                }
        }
        printf ("compare successful\n");
        exit (0);
}
 

FILES

/opt/lcg/include/gfal_api.h
/opt/lcg/lib/libgfal.so
/usr/local/lib/libcgsi_plugin_gsoap_2.3.so
/opt/globus/lib/libglobus_gssapi_gsi_gcc32dbg.so
/opt/globus/lib/libglobus_gss_assist_gcc32dbg.so
 

AUTHOR

Jean-Philippe Baud

 

Index

NAME
DESCRIPTION
RETURN VALUE
EXAMPLES
FILES
AUTHOR
This document was created by man2html, using the manual pages.
Time: 12:34:05 GMT, January 20, 2004