release notes | UserGuide: 4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 6.2, 7.0, 7.1, 7.2 (unreleased), 8.0, 8.1, 8.2, 9.0, 9.1, 9.2, 10.0, 10.1, 10.2, 7.2 (unreleased) | Book: 4.2, 5.0, 5.1, 5.2, 6.0, 6.1, 6.2, 7.0, 7.1, 7.2 (unreleased), 8.0, 8.1, 8.2, 9.0, 9.1, 9.2, 10.0, 10.1, 10.2, 7.2 (unreleased) | Wiki | Q&A black_bg

C - API to the dCache Access Protocol (dcap)

Library description

The libdcap library provides a POSIX like open, create, read, write and lseek functions to the dCache storage. In addition there are some specific functions for setting debug level, getting error messages and binding the library to a network interface.

The API

int dc_open(const char *path, int oflag, /* mode_t mode */...);

The dc_open() function connects to the dCache server, makes a request for file, creates a callback socket for a data connection and waits until the data connection will be established. The dc_open call, for reading an existing file, is blocked until this file is staged from the HSM to one of the dCache pools. Note that open for writing is allowed only for new files, e.g. modifing of an existing file is not possible. If the file is not located within the Pnfs file system, dc_open has the same behavior as the system open(2) call.

int dc_create(const char *path, mode_t mode);

The call dc_creat(path, mode) is equivalent to:
dc_open(path, O_WRONLY | O_CREAT | O_TRUNC, mode)

ssize_t dc_read(int fildes, void *buf, size_t nbytes);

The dc_read() function attempts to read nbyte bytes from the file associated with the open file descriptor, fildes, into the buffer pointed to by buf. If the fildes is not a valid dCache file descriptor, dc_read has the same behavior as the system read(2) call.

ssize_t dc_pread(int fildes, void *buf, size_t nbytes, off_t offset);

The dc_pread() function performs the same action as dc_read(), except that it reads from a given position in the file without changing the file pointer. The first three arguments to dc_pread() are the same as dc_read() with the addition of a fourth argument offset for the desired position inside the file.

ssize_t dc_write(int fildes,const void *buf, size_t nbytes);

The dc_write() function attempts to write nbyte bytes from the buffer pointed to by buf to the file associated with the open file descriptor, fildes. If the fildes is not a valid dCache file descriptor, dc_write has the same behavior as the system write(2) call.

ssize_t dc_pwrite(int fildes, const void *buf, size_t nbytes, off_t offset);

The dc_pwrite() function performs the same action as dc_write(), except that it writes at given position in the file without changing the file pointer. The first three arguments to dc_pwrite() are the same as dc_write() with the addition of a fourth argument offset for the desired position inside the file.

int dc_dup(int oldfd);

The dc_dup() function creates a copy of the file descriptor oldfd. If the oldfd is not a valid dCache file descriptor, dc_dup has the same behavior as the system dup(2) call.

int dc_access(const char *path, int mode);

The dc_access() function checks whether the process would be allowed to read, write or test for existence of the file (or other file system object) whose name is pathname.

mode is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.

R_OK, W_OK and X_OK request checking whether the file exists and has read, write and execute permissions, respectively. F_OK just requests checking for the exis tence of the file.

If the file is not located within the Pnfs file system, dc_access has the same behavior as the system access(2) call.

int dc_fsync(int fd);

The dc_fsync() function flushes all clinet's local data buffers do the write pool. If the fd is not a valid dCache file descriptor, dc_fsync has the same behavior as the system fsync(2) call.

off_t dc_lseek(int fildes, off_t offset, int whence);

The dc_lseek() function sets the file pointer associated with the open file descriptor specified by fildes as follows:

If whence is SEEK_SET, the pointer is set to offset bytes.

If whence is SEEK_CUR, the pointer is set to its current location plus offset.

If whence is SEEK_END, the pointer is set to the size of the file plus offset.

If the fildes is not a valid dCache file descriptor, dc_lseek has the same behavior as the system lseek(2) call.

int dc_close(int fildes);

The dc_close() closes the data connection to the dCache pool and frees the memory allocated by the dc_open call for the fildes file descriptor. The control connection is kept open for future dCache I/O operations. If fildes is not a valid dCache file descriptor, dc_close has the same behavior as the system close(2) call.

int dc_close2(int fildes);

The dc_close2() method releases all local resources associated with the given file descriptor without sending a close to the data server. This function has to be used as soon as an active filedescriptor crossed a fork.

void dc_setReplyHostName( char *hostname);

The dc_setReplyHostName() allows to bind data connection to a particular interface if the client host has several of them. By default the name as returned by hostname(1) function is used. If the DCACHE_REPLY enviroment variable is defined, the dc_setReplyHostName() function calls are ignored.

char * getDcapVersion();

The getDcapVersion() returns the pointer to a string which containing the dcap library version number. The returned pointer must not be freed by user.

void dc_setDebugLevel(int debugLevel);

The setDebugLevel() function defines the debug output level. The following values are accepted:
0: no output at all;
1: error messages only (default);
2: useful information;
4: speed information;
8: trace ( for developers only );
16: function calls sequence ( for developers only );
32: IO ( for developers only ).
The result of calling setDebugLevel() is bitwise OR with current value. To reset the debug level client have to call setDebugLevel() with debugLevel 0.

void debug(int level, const char *format, ...);

Obsolete, See dc_debug().

void dc_debug(int level, const char *format, ...);

The dc_debug() function prints a message to standard error. The format is equivalent to the printf(1) function. The level is used to specify the corresponding debug level. The following constants are available:

ERROR error messages

INFO some status information, which appears once per execution.

TRACE: event tracing, which appears at each dCache internal or external funcions call.

void dc_error(const char *msg);

Obsolete. See dc_perror.

void dc_perror(const char *msg);

The dc_perror() function reports the current dCache error status together with the system error status to standard error. The printout is preceeded by msg. If msg is a pointer to NULL or an empty line ("") the error status is not prefixed.

const char *dc_strerror(int errnum);

The dc_strerror() function maps the error number in errnum to an error message string, and returns a pointer to that string. It uses the same set of error messages as dc_perror. The returned string should not be overwritten. The dc_strerror() function returns NULL if errnum is out-of-range.

void dc_noBuffering(int fd);

The dc_noBuffering() function disables the read ahead option for the dc_read calls on the given fd file descriptor. The dc_noBuffering has to be called before the first dc_read call. All later invocations will be ignored. By default, the read ahead option is enabled if the file has been opened with the O_RDONLY flag. If the fd is not associated with the opened file in the pnfs file system or DCACHE_RAHEAD enviroment variable is defined, the dc_noBuffering is silently ignored.

void dc_setBufferSize(int fd, ssize_t nbytes);

The dc_setBufferSize() function sets the read ahead buffer size to nbytes for the given fd file descriptor. The default size of the read ahead buffer is 1Mb, if DCACHE_RA_BUFFER enviroment variable is does not override it. If thefd is not associated with the opened file in the pnfs file system, the dc_setBufferSize is silently ignored.

int dc_stage(const char *path, time_t n, const char *location);

The dc_stage() function allows to send a request for file path to be staged to the dCache Pool for location location after n seconds. If location is NULL, the local host name will be used. The location can be host name as well as IP address with netmask, e.q. a.b.c.d/24. The dc_stage() returns 0 on success and -1 on failure. The dc_stage() should be used as a hint only.

int dc_check(const char *path, const char *location);

The dc_check() function allows to check dCache Pools for location location for avialability of file path. If location is NULL, the local host name will be used. The location can be host name as well as IP address with netmask, e.q. a.b.c.d/24. The dc_check() returns 0 on success and -1 on failure. The errno will be set to EAGAIN if file not in the chache. The dc_check() should be used as a hint only.

void dc_unsafeWrite(int dest);

The dc_unsafeWrite() function improves the speed of write operations significantly by issueing only one confirmation of (un)successful write at dc_close(). Not recommended for unreproducible sources (e.g. direct output of application).

void dc_setCallbackPortRange(unsigned short first_port, unsigned short last_port);

The dc_setCallbackPortRange() function allows to specify a range of TCP ports, which can be used for callback data connection (e.g. to use with firewall).

void dc_setCallbackPort(unsigned short callback_port);

The dc_setCallbackPort() function are equivalent to dc_setCallbackPortRange(), but with single port specification insted of ports range.

void dc_setTCPReceiveBuffer( int newSize )

The dc_setTCPReciveBuffer() function allows to change the default TCP recive buffer size (256Kb) to newSize. All following dc_open() will be affected.

void dc_setTCPSendBuffer( int newSize )

The dc_setTCPSendBuffer() function allows to change the default TCP send buffer size (256Kb) to newSize. All following dc_open() will be affected.

void dc_noCheckSum(int fd)

The dc_noCheckSum() function disables a check sum calculation durind write. It is not recomended to switch off check sum calculation, unless there is a performance issue.

void dc_unlink(const char *path)

The dc_unlink() deletes a name from the filesystem. If path is not a dCache url, dc_unlink has a same behavior as a system unlink(2).

void dc_rmdir(const char *path)

The dc_rmdir() deletes a directory, which must be empty. If path is not a dCache url, dc_rmdir has a same behavior as a system rmdir(2).

void dc_mkdir(const char *path, mode_t mode )

The dc_mkdir() attempts to create a directory named path. mode specifies the permissions to use. If path is not a dCache url, dc_mkdir has a same behavior as a system mkdir(2).

void dc_chmod(const char *path, mode_t mode )

The dc_chmod() changes the mode of the file given by path. If path is not a dCache url, dc_chmod has a same behavior as a system chmod(2).

void dc_setClientActive()

The dc_setClientActive() lets the client to connect to the if dCache door supports 'passive' mode . Can be activated by DCACHE_CLIENT_ACTIVE environment variable.