CCDS Programming Interface

The following pages contain documentation of the CCDS programming interface functions in alphabetical order.

ccds_close CCDS ccds_close

• NAME
  • ccds_close - close file descriptor
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_close( int fdes );
• DESCRIPTION
  • ccds_close() closes the file descriptor specified by fdes.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned:
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_BADF
    not an open file descriptor
  • CCDS_INVID
    not owner of file descriptor
  • CCDS_ETPORT
    error in underlying transport system

ccds_delete CCDS ccds_delete

• NAME
  • ccds_delete - delete a CCDS object
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • void ccds_delete( char *name);
• DESCRIPTION
  • ccds_delete() deletes the CCDS object pointed to by name. The object is not actually removed from the CCDS until it has been closed by every process that has opened it. Only the owner of an object can successfully delete an object.

ccds_export CCDS ccds_export

• NAME
  • ccds_export - export an object from CCDS
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_export( char *dstname, char *name );
• DESCRIPTION
  • ccds_export() moves the object pointed to by name to the file pointed to by dstname.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_EFTBL
    server file table full
  • CCDS_ECFTBL
    client file table full
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_ELOCK
    section is locked
  • CCDS_ESRC
    can't open src
  • CCDS_ENAME
    bad name

ccds_import CCDS ccds_import

• NAME
  • ccds_import - import an object to CCDS
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_import( char *srcname, char *name, int mode, int type );
• DESCRIPTION
  • ccds_import() imports the object pointed to by srcname into CCDS where it is reference to by the name pointed to by name. The mode argument specifies the access permission bits for the object and is determined as the bitwise OR of: CCDS_IR, CCDS_IW, CCDS_IX, giving read, write, and execute permission respectively for the file to all members of the CCDS. Permissions are currently not supported by CCDS.
  • Only type argument currently supported is
    • CCDS_NATIVEFILE
      File is accessed via CCDS
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_EFTBL
    server file table full
  • CCDS_ECFTBL
    client file table full
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_EINSUF
    insufficient system resources
  • CCDS_ESRC
    can't open src
  • CCDS_ENAME
    bad name

ccds_init CCDS ccds_init

• NAME
  • ccds_init - initialize ccds
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_init( int argc, char **argv );
• DESCRIPTION
  • ccds_init() performs various initialization functions. argv is a pointer to a string of options, argv must contain a -session option followed by a session name. ccds_init() accepts optional -path option followed by path to local data storage and -debug option followed by debug level 0 - 6. Default path is /tmp and default debug level is 0 (no debug output). ccds_init() spawns a data server on the local machine if a server in the named session is not already active.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_FATAL
    fatal system error
  • CCDS_ETPORT
    error in underlying transport system

ccds_leave CCDS ccds_leave

• NAME
  • ccds_leave - leave ccds
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_leave( );
• DESCRIPTION
  • ccds_leave() causes the process to leave the ccds. All open files are closed and all objects owned by the calling process on data servers are deleted. The ccds data servers will terminate when ccds is empty and all processes have called ccds_leave().
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_ERROR
    ccds error

ccds_lock CCDS ccds_lock

• NAME
  • ccds_lock - lock segment of file
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_lock( int fdes, long size );
  • int ccds_olock( int fdes, ccds_offt offset, long size );
• DESCRIPTION
  • ccds_lock() allows a segment of the file associated with fdes to be locked. Only one lock can be associated with each fdes.
  • ccds_lock() locks size bytes from the current file offset pointer position. If part of that segment is already locked, then ccds_lock() returns with an error. The file pointer remains unchanged.
  • ccds_olock() performs the same action as ccds_lock(), but begins locking from offset file position.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_BADF
    not an open file descriptor
  • CCDS_INVID
    not owner of file descriptor
  • CCDS_ELOCK
    section is locked
  • CCDS_ENLOCK
    number of locks exceeded

ccds_ls CCDS ccds_ls

• NAME
  • ccds_ls - list content of CCDS
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_ls( ccds_item_t **buf, int *nitem );
• DESCRIPTION
  • ccds_ls() returns a list of content of CCDS. Upon return from ccds_ls() *buf points to an array of nitem items of type ccds_item_t. ccds_ls() allocates memory for the buffer that should be freed by the calling process.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_ETPORT
    error in underlying transport system

ccds_lseek CCDS ccds_lseek

• NAME
  • ccds_lseek - move read/write file pointer
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • ccds_offt ccds_lseek(int fdes, ccds_offt offset, int whence);
• DESCRIPTION
  • ccds_lseek() sets the file pointer associated with fdes.
  • The whence argument determines ccds_lseek operation as follows:
    • CCDS_SEEK_SET
      the pointer is set to offset bytes
    • CCDS_SEEK_CUR
      the pointer is set to its current position plus offset
• RETURN VALUES
  • Upon successful completion, the resulting non-negative file pointer is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_BADF
    not an open file descriptor
  • CCDS_INVID
    not owner of file descriptor
  • CCDS_ELOCK
    section is locked
  • CCDS_ETPORT
    error in underlying transport system

ccds_migrate CCDS ccds_migrate

• NAME
  • ccds_migrate - Migrate object to local data server
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_migrate( char *name );
• DESCRIPTION
  • ccds_migrate moves the object pointed to by name to the local data server for the calling process. Currently an object has to be closed before it can migrate.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_ERROR
    ccds error

ccds_notify CCDS ccds_notify

• NAME
  • ccds_notify - enable or disable object notification change callback
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • void ccds_notify( void ( *cb )( ccds_item_t *buf, int nitem ) );
• DESCRIPTION
  • ccds_notify() enables a callback for object notification changes. Three types of object changes will result in a call of cb: (1) addition of object to CCDS, (2) deletion of object from CCDS, and (3) change of object properties. Currently only (1) and (2) are implemented. cb is a pointer to a user supplied callback function. cb has two parameters buf and nitem.
    • ccds_item_t buf
      pointer to an array of elements. buf is freed after returning from cb.
    • nitem
      number of elements in buf
  • The type ccds_item_t is defined as:

    	typedef struct {
                    char name[ CCDS_MAX_OBJECTNAME ];
                    int type;
                    int owner_id;
                    int cflag;
            } ccds_item_t;

  • Where the fields have the following semantics
    • char name[]
      name of object
    • int type
      type of object, currently only CCDS_NATIVEFILE is supported
    • int owner_id
      unique id of owner
    • int cflag
      change flag, can take the values of CCDS_OBJECT_ADD and CCDS_OBJECT_DELETE signifying that the object is added, respectively deleted.
  • When notification is enabled, cb will be called to reflect the current global state of CCDS.
  • To disable notification use ccds_notify( NULL );

ccds_open CCDS ccds_open

• NAME
  • ccds_open - open a file for reading or writing
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_open( char *name, int oflag, int mode, int view, int lflag );
• DESCRIPTION
  • ccds_open() opens a file descriptor for the file pointed to by name. oflag is determined by bitwise OR of one of:
    • CCDS_RDONLY
      open for reading only, and select shared read pointer in shared filepointer operation. See view parameter.
    • CCDS_WRONLY
      open for writing only, and select shared write pointer in shared filepointer operation. See view parameter.
    • CCDS_RDWR
      open for reading and writing, and select shared write pointer in shared filepointer operation. See view parameter.
    • and any combination of:
    • CCDS_APPEND
      file pointer is set to end of file prior to each write.
    • CCDS_CREAT
      if the file does not exist, then it is created with access permission set to mode.
    • CCDS_CREATONLY
      same as CCDS_CREATE, but if file already exists then an error value is returned.
  • The mode argument specifies the access permission bits when a file is created, and is determined as the bitwise OR of: CCDS_IR, CCDS_IW, CCDS_IX, giving read, write, and execute permission respectively for the file to all members of the CCDS. The mode argument and permissions are currently not supported by CCDS.
  • The argument view sets one of the following file views:
    • CCDS_SHARED
      A single file pointer is shared among all processes that open the file with the same oflag parameter. CCDS allows two different shared file pointers per file. One shared file pointer is assigned to processes that open with CCDS_SHARED and oflag parameter CCDS_RDONLY set. The second shared file pointer is assigned to processes that open with CCDS_SHARED and oflag parameter CCDS_WRONLY or CCDS_RDWR set.
    • CCDS_LOCAL
      The file is accessed via a local file pointer.
  • Permission to open the file with different oflag and view parameters is controlled by the lflag parameter. lflag can take one of the following values:
    • CCDS_UNRESTR
      File can be opened by any combination of oflag and view parameters.
    • CCDS_RESTR
      File can only be opened with one shared pointer. This means that all shared opens must have the same oflag parameter. CCDS_RESTR is currently not supported.
    • CCDS_EXCLUV
      File can not be opened by other processes.
• NOTE
  • A file descriptor can not be shared with another process.
• RETURN VALUES
  • Upon successful completion, a file descriptor is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_EFTBL
    server file table full
  • CCDS_ECFTBL
    client file table full
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_ELFLAG
    file cannot be opened with lflag
  • CCDS_EXIST
    file already exists
  • CCDS_ENAME
    bad name

ccds_property CCDS ccds_property

• NAME
  • ccds_property - properties of an CCDS object
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_property( char *name, ccds_propt *buf );
• DESCRIPTION
  • ccds_property() returns the object properties for the CCDS object pointed to by name.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_ENAME
    bad name

ccds_read CCDS ccds_read

• NAME
  • ccds_read - read from a file
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • ccds_ssizet ccds_read(int fdes, char *buf, ccds_sizet nbyte);
  • ccds_ssizet ccds_oread(int fdes, char *buf, ccds_sizet nbyte, ccds_offt offset);
  • ccds_ssizet ccds_pread(int fdes, char *buf, ccds_sizet nbyte, ccds_offt offset);
• DESCRIPTION
  • ccds_read() reads nbyte bytes from the file specified in fdes, starting at the current file pointer position, into the buffer pointed to by buf. ccds_read() stops reading bytes if an end-of-file or error condition is encountered. The file pointer is incremented by the number of bytes read.
  • ccds_oread() performs the same action as ccds_read(), except that the starting offset is specified by the offset parameter.
  • ccds_pread() performs the same action as ccds_oread(), except that the file pointer associated with fdes is unchanged.
• RETURN VALUES
  • Upon successful completion, the number of bytes read is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_BADF
    not an open file descriptor
  • CCDS_INVID
    not owner of file descriptor
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_EINSUF
    insufficient system resources
  • CCDS_ELOCK
    section is locked

ccds_unimport CCDS ccds_unimport

• NAME
  • ccds_unimport - unimport an object from CCDS
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_unimport( char *dstname, char *name );
• DESCRIPTION
  • ccds_unimport() moves the object pointed to by name to the file pointed to by dstname. The object is removed from CCDS following successful unimport. Only the owner of an object can unimport.
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EACCES
    File not found or can not create
  • CCDS_EFTBL
    server file table full
  • CCDS_ECFTBL
    client file table full
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_ELOCK
    section is locked
  • CCDS_ESRC
    can't open src
  • CCDS_ENAME
    bad name

ccds_unlock CCDS ccds_unlock

• NAME
  • ccds_unlock - unlock file
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • int ccds_unlock( int fdes );
• DESCRIPTION
  • ccds_unlock() unlocks the segment associated with fdes previously locked by ccds_lock() or ccds_olock()
• RETURN VALUES
  • Upon successful completion, a value of 0 is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_BADF
    not an open file descriptor
  • CCDS_ETPORT
    error in underlying transport system

ccds_write CCDS ccds_write

• NAME
  • ccds_write - write to a file
• SYNOPSIS
  • #include <ccds.h>
  • #include <ccds_errno.h>
  • ccds_ssizet ccds_write(int fdes, char *buf, ccds_sizet nbyte);
  • ccds_ssizet ccds_owrite(int fdes, char *buf, ccds_sizet nbyte, ccds_offt offset);
  • ccds_ssizet ccds_pwrite(int fdes, char *buf, ccds_sizet nbyte, ccds_offt offset);
• DESCRIPTION
  • ccds_write() writes nbyte bytes to the file specified in fdes, beginning at the current file pointer position, from the buffer pointed to by buf. ccds_write() stops writing if an error condition is encountered. The file pointer is incremented by the number of bytes written.
  • ccds_owrite() performs the same action as ccds_write(), except that the starting offset is specified by the offset parameter.
  • ccds_pwrite() performs the same action as ccds_owrite(), except that the file pointer associated with fdes is unchanged.
• RETURN VALUES
  • Upon successful completion, the number of bytes written is returned; otherwise, a negative error value is returned.
• ERROR VALUES
  • The following error values can be returned
  • CCDS_EFSTM
    error in underlying file system
  • CCDS_BADF
    not an open file descriptor
  • CCDS_INVID
    not owner of file descriptor
  • CCDS_ETPORT
    error in underlying transport system
  • CCDS_EINSUF
    insufficient system resources
  • CCDS_ELOCK
    section is locked