The primary user API for accessing Chirp servers. More...

#include "chirp_types.h"
#include <sys/types.h>
#include <stdio.h>
#include <dirent.h>

Functions
struct chirp_file *	chirp_reli_open (const char host, const char path, INT64_T flags, INT64_T mode, time_t stoptime)
	Creates or opens a file in preparation for I/O. More...

INT64_T	chirp_reli_close (struct chirp_file *file, time_t stoptime)
	Closes an open file. More...

INT64_T	chirp_reli_pread (struct chirp_file file, void buffer, INT64_T length, INT64_T offset, time_t stoptime)
	Read data from a file. More...

INT64_T	chirp_reli_pwrite (struct chirp_file file, const void buffer, INT64_T length, INT64_T offset, time_t stoptime)
	Write data to a file. More...

INT64_T	chirp_reli_pread_unbuffered (struct chirp_file file, void buffer, INT64_T length, INT64_T offset, time_t stoptime)
	Read data from a file without buffering. More...

INT64_T	chirp_reli_pwrite_unbuffered (struct chirp_file file, const void buffer, INT64_T length, INT64_T offset, time_t stoptime)
	Write data to a file without buffering. More...

INT64_T	chirp_reli_sread (struct chirp_file file, void buffer, INT64_T length, INT64_T stride_length, INT64_T stride_skip, INT64_T offset, time_t stoptime)
	Strided read from a file. More...

INT64_T	chirp_reli_swrite (struct chirp_file file, const void buffer, INT64_T length, INT64_T stride_length, INT64_T stride_skip, INT64_T offset, time_t stoptime)
	Strided write to a file. More...

INT64_T	chirp_reli_fstat (struct chirp_file file, struct chirp_stat info, time_t stoptime)
	Get file status. More...

INT64_T	chirp_reli_fstatfs (struct chirp_file file, struct chirp_statfs info, time_t stoptime)
	Get file system status. More...

INT64_T	chirp_reli_fchown (struct chirp_file *file, INT64_T uid, INT64_T gid, time_t stoptime)
	Change the ownership of a file. More...

INT64_T	chirp_reli_fchmod (struct chirp_file *file, INT64_T mode, time_t stoptime)
	Change the mode bits of a file. More...

INT64_T	chirp_reli_ftruncate (struct chirp_file *file, INT64_T length, time_t stoptime)
	Truncate an open file. More...

INT64_T	chirp_reli_flush (struct chirp_file *file, time_t stoptime)
	Flush any pending changes to a file. More...

INT64_T	chirp_reli_getfile (const char host, const char path, FILE *stream, time_t stoptime)
	Get an entire file efficiently. More...

INT64_T	chirp_reli_getfile_buffer (const char host, const char path, char **buffer, time_t stoptime)
	Get an entire file efficiently to memory. More...

INT64_T	chirp_reli_putfile (const char host, const char path, FILE *stream, INT64_T mode, INT64_T length, time_t stoptime)
	Put an entire file efficiently. More...

INT64_T	chirp_reli_putfile_buffer (const char host, const char path, const void *buffer, INT64_T mode, size_t length, time_t stoptime)
	Put an entire file efficiently from memory. More...

CHIRP_SEARCH *	chirp_reli_opensearch (const char host, const char paths, const char *pattern, int flags, time_t stoptime)
	Open a file search stream Performs a search operation on the Chirp server and stores its results to be read via readsearch More...

INT64_T	chirp_reli_getlongdir (const char host, const char path, chirp_longdir_t callback, void *arg, time_t stoptime)
	Get a detailed directory listing. More...

INT64_T	chirp_reli_getdir (const char host, const char path, chirp_dir_t callback, void *arg, time_t stoptime)
	Get a simple directory listing. More...

struct chirp_dir *	chirp_reli_opendir (const char host, const char path, time_t stoptime)
	Open a directory for listing. More...

struct chirp_dirent *	chirp_reli_readdir (struct chirp_dir *dir)
	Read one item from a directory. More...

void	chirp_reli_closedir (struct chirp_dir *dir)
	Close a directory. More...

INT64_T	chirp_reli_getacl (const char host, const char path, chirp_dir_t callback, void *arg, time_t stoptime)
	Get an access control list. More...

INT64_T	chirp_reli_setacl (const char host, const char path, const char subject, const char rights, time_t stoptime)
	Modify an access control list. More...

INT64_T	chirp_reli_resetacl (const char host, const char path, const char *rights, time_t stoptime)
	Reset an access control list. More...

INT64_T	chirp_reli_locate (const char host, const char path, chirp_loc_t callback, void *arg, time_t stoptime)
	Identify the true location of a path. More...

INT64_T	chirp_reli_whoami (const char host, char subject, INT64_T length, time_t stoptime)
	Return the caller's identity. More...

INT64_T	chirp_reli_whoareyou (const char host, const char rhost, char *subject, INT64_T length, time_t stoptime)
	Return the server's identity against another server. More...

INT64_T	chirp_reli_unlink (const char host, const char path, time_t stoptime)
	Delete a file. More...

INT64_T	chirp_reli_rename (const char host, const char path, const char *newpath, time_t stoptime)
	Rename a file or directory. More...

INT64_T	chirp_reli_link (const char host, const char path, const char *newpath, time_t stoptime)
	Create a hard link. More...

INT64_T	chirp_reli_symlink (const char host, const char path, const char *newpath, time_t stoptime)
	Create a symbolic link. More...

INT64_T	chirp_reli_readlink (const char host, const char path, char *buf, INT64_T length, time_t stoptime)
	Examine a symbolic link. More...

INT64_T	chirp_reli_mkdir (const char host, const char path, INT64_T mode, time_t stoptime)
	Create a new directory. More...

INT64_T	chirp_reli_mkdir_recursive (const char host, const char path, INT64_T mode, time_t stoptime)
	Create a new directory recursively. More...

INT64_T	chirp_reli_rmdir (const char host, const char path, time_t stoptime)
	Delete a directory if it is empty. More...

INT64_T	chirp_reli_rmall (const char host, const char path, time_t stoptime)
	Delete a directory recursively. More...

INT64_T	chirp_reli_stat (const char host, const char path, struct chirp_stat *info, time_t stoptime)
	Get file status. More...

INT64_T	chirp_reli_lstat (const char host, const char path, struct chirp_stat *info, time_t stoptime)
	Get file or link status. More...

INT64_T	chirp_reli_statfs (const char host, const char path, struct chirp_statfs *info, time_t stoptime)
	Get filesystem status. More...

INT64_T	chirp_reli_access (const char host, const char path, INT64_T flags, time_t stoptime)
	Check access permissions. More...

INT64_T	chirp_reli_chmod (const char host, const char path, INT64_T mode, time_t stoptime)
	Change mode bits. More...

INT64_T	chirp_reli_chown (const char host, const char path, INT64_T uid, INT64_T gid, time_t stoptime)
	Change the ownership of a file. More...

INT64_T	chirp_reli_lchown (const char host, const char path, INT64_T uid, INT64_T gid, time_t stoptime)
	Change the ownership of a file or link. More...

INT64_T	chirp_reli_truncate (const char host, const char path, INT64_T length, time_t stoptime)
	Truncate a file. More...

INT64_T	chirp_reli_utime (const char host, const char path, time_t actime, time_t modtime, time_t stoptime)
	Change the modification times of a file. More...

INT64_T	chirp_reli_hash (const char host, const char path, const char *algorithm, unsigned char digest[CHIRP_DIGEST_MAX], time_t stoptime)
	Checksum a remote file. More...

INT64_T	chirp_reli_md5 (const char host, const char path, unsigned char digest[CHIRP_DIGEST_MAX], time_t stoptime)
	Checksum a remote file. More...

INT64_T	chirp_reli_setrep (const char host, const char path, int nreps, time_t stoptime)
	Set replication factor. More...

INT64_T	chirp_reli_remote_debug (const char host, const char flag, time_t stoptime)
	Set the debug options on the remote server. More...

INT64_T	chirp_reli_localpath (const char host, const char path, char *localpath, int length, time_t stoptime)
	Return the local path of a file. More...

INT64_T	chirp_reli_audit (const char host, const char path, struct chirp_audit **list, time_t stoptime)
	Measure remote space consumption. More...

INT64_T	chirp_reli_thirdput (const char host, const char path, const char thirdhost, const char thirdpath, time_t stoptime)
	Third party transfer. More...

INT64_T	chirp_reli_mkalloc (const char host, const char path, INT64_T size, INT64_T mode, time_t stoptime)
	Create a space allocation. More...

INT64_T	chirp_reli_lsalloc (const char host, const char path, char allocpath, INT64_T total, INT64_T *inuse, time_t stoptime)
	List a space allocation. More...

INT64_T	chirp_reli_bulkio (struct chirp_bulkio *list, int count, time_t stoptime)
	Perform multiple I/O operations in bulk. More...

INT64_T	chirp_reli_blocksize_get ()
	Return the current buffer block size. More...

void	chirp_reli_blocksize_set (INT64_T bs)
	Set the buffer block size. More...

void	chirp_reli_cleanup_before_fork ()
	Prepare to fork in a parallel program. More...

void	chirp_reli_disconnect (const char *host)
	Closes the link to the host, if active. More...

Detailed Description

The primary user API for accessing Chirp servers.

chirp_reli.h is designed to look similar to the Unix I/O interface. It is called "reli" because it is "reliable". Each function call here has the capabaility to detect and retry a large number of network and server errors with an exponential backoff, until a user-defined time limit is reached. The caller need not worry about connecting to or disconnecting from servers.

All functions in this file have several common calling conventions.

Parameters

host	A hostname may be a domain name or an IP address, followed by an optional colon and port number. If not given, the port number is assumed to by the default Chirp port of 9094.
path	A pathname identifies a file from the root of the given file server, and must start with a slash. The Chirp protocol allows pathnames to contain any printable ASCII character except a newline.
stoptime	All functions accept a final argument `time_t stoptime` which indicates the absolute time at which to abort. For example, to try an operation for 60 seconds, pass `time(0)+60` as `stoptime`. Any transient network failures will be silently retried until this timeout is reached.

Returns: On success, all functions return an integer greater than or equal to zero, and errno may have any arbitrary value. On failure, all return an integer less than zero, and set errno to the reason for the failure. (chirp_reli_open is the only exception to this rule.) The caller may invoke strerror(errno) to generate a human-readable string representing the error.

Function Documentation

struct chirp_file* chirp_reli_open	(	const char *	host,
		const char *	path,
		INT64_T	flags,
		INT64_T	mode,
		time_t	stoptime
	)

Creates or opens a file in preparation for I/O.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
flags	Any of the following Unix open flags ORed together: O_RDONLY - Open for reading only. O_WRONLY - Open for writing only. O_RDWR - Open for both read and write. O_APPEND - Open for appending to the file. O_CREAT - Create the file if it does not exist. O_TRUNC - Truncate the file to zero bytes. O_SYNC - Force synchronous writes to disk.
mode	The Unix mode bits to be given to the file. Chirp only honors the owner component of the mode bits. Typical choices are `0700` for an executable, and `0600` for a data file. (Note the leading zero to indicate octal data.)
stoptime	The absolute time at which to abort.

Returns: On success, returns a pointer to a chirp_file. On failure, returns zero and sets errno appropriately.

See Also: chirp_reli_pread, chirp_reli_pwrite, chirp_reli_sread, chirp_reli_swrite, chirp_reli_fstat, chirp_reli_fstatfs chirp_reli_fchmod, chirp_reli_fchown, chirp_reli_ftruncate, chirp_reli_flush, chirp_reli_close

INT64_T chirp_reli_close	(	struct chirp_file *	file,
		time_t	stoptime
	)

Closes an open file.

Note that a close may need to write buffered data to disk before completing, so chirp_reli_close can fail. If chirp_reli_close indicates failures, the struct chirp_file is deallocated and can no longer be used, but the caller must assume some previously written data was lost.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
stoptime	The absolute time at which to abort.

See Also: chirp_file_open

INT64_T chirp_reli_pread	(	struct chirp_file *	file,
		void *	buffer,
		INT64_T	length,
		INT64_T	offset,
		time_t	stoptime
	)

Read data from a file.

Small reads may be buffered into large reads for efficiency.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to destination buffer.
length	Number of bytes to read.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually read, which may be less than that requested. On end of file, returns zero. On failure, <0 and sets errno.

See Also: chirp_reli_open, chirp_reli_pread_unbuffered, chirp_reli_sread

INT64_T chirp_reli_pwrite	(	struct chirp_file *	file,
		const void *	buffer,
		INT64_T	length,
		INT64_T	offset,
		time_t	stoptime
	)

Write data to a file.

Small writes may be buffered together into large writes for efficiency.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to source buffer.
length	Number of bytes to write.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually written, which may be less than requested. On failure, <0 and sets errno.

Parameters

stoptime The absolute time at which to abort.

See Also: chirp_reli_open, chirp_reli_swrite

INT64_T chirp_reli_pread_unbuffered	(	struct chirp_file *	file,
		void *	buffer,
		INT64_T	length,
		INT64_T	offset,
		time_t	stoptime
	)

Read data from a file without buffering.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to destination buffer.
length	Number of bytes to read.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually read. If the end of file has been reached, returns zero. On failure, <0 and sets errno.

See Also: chirp_reli_open, chirp_reli_pread, chirp_reli_sread

INT64_T chirp_reli_pwrite_unbuffered	(	struct chirp_file *	file,
		const void *	buffer,
		INT64_T	length,
		INT64_T	offset,
		time_t	stoptime
	)

Write data to a file without buffering.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to source buffer.
length	Number of bytes to write.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually written. On failure, <0 and sets errno.

See Also: chirp_reli_open, chirp_reli_pwrite, chirp_reli_swrite

INT64_T chirp_reli_sread	(	struct chirp_file *	file,
		void *	buffer,
		INT64_T	length,
		INT64_T	stride_length,
		INT64_T	stride_skip,
		INT64_T	offset,
		time_t	stoptime
	)

Strided read from a file.

Reads stride_length bytes every stride_skip bytes, starting from offset up to a maximum of length bytes read.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to destiation buffer.
length	Maximum number of bytes to read.
stride_length	Bytes to read in each stride.
stride_skip	Bytes to skip between each stride.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually read, which may be less than requested. On failure, <0 and sets errno.

Parameters

stoptime The absolute time at which to abort.

See Also: chirp_reli_open, chirp_reli_pread, chirp_reli_pwrite, chirp_reli_sread, chirp_reli_swrite

INT64_T chirp_reli_swrite	(	struct chirp_file *	file,
		const void *	buffer,
		INT64_T	length,
		INT64_T	stride_length,
		INT64_T	stride_skip,
		INT64_T	offset,
		time_t	stoptime
	)

Strided write to a file.

Writes stride_length bytes every stride_skip bytes, starting from offset up to a maximum of length bytes written.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
buffer	Pointer to destiation buffer.
length	Maximum number of bytes to write.
stride_length	Bytes to write in each stride.
stride_skip	Bytes to skip between each stride.
offset	Beginning offset in file.
stoptime	The absolute time at which to abort.

Returns: On success, returns the number of bytes actually written, which may be less than requested. On failure, <0 and sets errno.

Parameters

stoptime The absolute time at which to abort.

See Also: chirp_reli_open, chirp_reli_pread, chirp_reli_pwrite, chirp_reli_sread, chirp_reli_swrite

INT64_T chirp_reli_fstat	(	struct chirp_file *	file,
		struct chirp_stat *	info,
		time_t	stoptime
	)

Get file status.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
info	A pointer to a chirp_stat structure to fill.
stoptime	The absolute time at which to abort.

Returns: >=0 on success, <0 on failure.

See Also: chirp_reli_open, chirp_stat

INT64_T chirp_reli_fstatfs	(	struct chirp_file *	file,
		struct chirp_statfs *	info,
		time_t	stoptime
	)

Get file system status.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
info	A pointer to a chirp_statfs structure to fill.
stoptime	The absolute time at which to abort.

Returns: >=0 on success, <0 on failure.

See Also: chirp_reli_open, chirp_reli_statfs

INT64_T chirp_reli_fchown	(	struct chirp_file *	file,
		INT64_T	uid,
		INT64_T	gid,
		time_t	stoptime
	)

Change the ownership of a file.

Deprecated:: Note that the current Chirp file server does not make use of the Unix owner field, see chirp_reli_setacl instead.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
uid	The new user ID.
gid	The new group ID.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_chown, chirp_reli_setacl, chirp_reli_getacl

INT64_T chirp_reli_fchmod	(	struct chirp_file *	file,
		INT64_T	mode,
		time_t	stoptime
	)

Change the mode bits of a file.

The mode bits may set group/other permissions. If the file is a not a directory, the mode bits may also set user execute. See chirp_reli_setacl for alternate strong authorization control.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
mode	The new mode bits, typically `0700` for an executable or `0600` for a data file.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_chmod, chirp_reli_setacl, chirp_reli_getacl

INT64_T chirp_reli_ftruncate	(	struct chirp_file *	file,
		INT64_T	length,
		time_t	stoptime
	)

Truncate an open file.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
length	The new length of the file.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_open, chirp_reli_truncate

INT64_T chirp_reli_flush	(	struct chirp_file *	file,
		time_t	stoptime
	)

Flush any pending changes to a file.

To improve performance, Chirp buffers small writes to files. These writes might not be forced to disk until a later write or a call to chirp_reli_close. To force any buffered writes to disk, call this function.

Parameters

file	A chirp_file handle returned by chirp_reli_open.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_close

INT64_T chirp_reli_getfile	(	const char *	host,
		const char *	path,
		FILE *	stream,
		time_t	stoptime
	)

Get an entire file efficiently.

Reads an entire remote file, and write the contents to a standard FILE stream. To get an entire directory tree, see chirp_recursive_get instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
stream	A standard FILE stream obtained from fopen(). Such a stream may be obtained from fopen(), or could be the standard globals `stdin`, `stdout`, or `stderr`.
stoptime	The absolute time at which to abort.

Returns: The size in bytes of the file, or less than zero on error.

See Also: chirp_reli_open

INT64_T chirp_reli_getfile_buffer	(	const char *	host,
		const char *	path,
		char **	buffer,
		time_t	stoptime
	)

Get an entire file efficiently to memory.

Reads an entire remote file into newly allocated memory. To get an entire directory tree, see chirp_recursive_get instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
buffer	A pointer to an uninitialized pointer. On success, this pointer will point to newly allocated memory containing the file. The caller must then release the member by calling free().
stoptime	The absolute time at which to abort.

Returns: The size of the file in bytes, or less than zero on error.

INT64_T chirp_reli_putfile	(	const char *	host,
		const char *	path,
		FILE *	stream,
		INT64_T	mode,
		INT64_T	length,
		time_t	stoptime
	)

Put an entire file efficiently.

Reads data out of a standard I/O stream and writes it to a remote file. To put an entire directory tree, see chirp_recursive_put instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
stream	A standard FILE stream obtained from fopen(). Such a stream may be obtained from fopen(), or could be the standard globals `stdin`, `stdout`, or `stderr`.
mode	The Unix mode bits to give to the remote file, typically `0700` for an executable or `0600` for a data file.
length	The length in bytes of the file to write.
stoptime	The absolute time at which to abort.

Returns: The size of the file in bytes, or less than zero on error.

INT64_T chirp_reli_putfile_buffer	(	const char *	host,
		const char *	path,
		const void *	buffer,
		INT64_T	mode,
		size_t	length,
		time_t	stoptime
	)

Put an entire file efficiently from memory.

Reads data out of memory and writes it to a remote file. To put an entire directory tree, see chirp_recursive_put instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
buffer	A pointer to the file data to write.
mode	The Unix mode bits to give to the remote file, typically `0700` for an executable or `0600` for a data file.
length	The length in bytes of the file to write.
stoptime	The absolute time at which to abort.

Returns: The size of the file in bytes, or less than zero on error.

CHIRP_SEARCH* chirp_reli_opensearch	(	const char *	host,
		const char *	paths,
		const char *	pattern,
		int	flags,
		time_t	stoptime
	)

Open a file search stream

Performs a search operation on the Chirp server and stores its results to be read via readsearch

Parameters

host	The name and port of the Chirp server to access.
paths	The pathnames of the directories to search.
pattern	The pattern to search for
flags	Bit flags controlling various aspects of the search
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_getlongdir	(	const char *	host,
		const char *	path,
		chirp_longdir_t	callback,
		void *	arg,
		time_t	stoptime
	)

Get a detailed directory listing.

Gets a detailed directory listing from a Chirp server, and then calls the callback once for each element in the directory.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
callback	The function to be called for each element in the listing.
arg	An optional convenience pointer that will be passed to the callback function.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_getdir	(	const char *	host,
		const char *	path,
		chirp_dir_t	callback,
		void *	arg,
		time_t	stoptime
	)

Get a simple directory listing.

Gets a simple directory listing from a Chirp server, and then calls the callback once for each element in the directory. This is a low-level function, you may find chirp_reli_opendir easier to use.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
callback	The function to be called for each element in the listing.
arg	An optional convenience pointer that will be passed to the callback function.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_opendir

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

struct chirp_dir* chirp_reli_opendir	(	const char *	host,
		const char *	path,
		time_t	stoptime
	)

Open a directory for listing.

This function returns a pointer to an opened directory. You may then call chirp_reli_readdir to read directory elements one by one.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
stoptime	The absolute time at which to abort.

Returns: On success, returns a pointer to an opaque chirp_dir object. On failure, returns null.

See Also: chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir

Referenced by chirp.Client::ls().

struct chirp_dirent* chirp_reli_readdir ( struct chirp_dir * dir )

Read one item from a directory.

Accepts a pointer to a directory opened by chirp_reli_opendir and returns the next chirp_dirent object, which describes the name and properties of the next item in the list. Returns null when the list is complete. Note that this function has no timeout because it operates solely on memory structures.

Parameters

dir	A pointer to a directory returned from chirp_reli_opendir.

Returns: On success, returns a pointer to a chirp_dirent object. Returns null when the list is complete.

See Also: chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir

Referenced by chirp.Client::ls().

void chirp_reli_closedir ( struct chirp_dir * dir )

Close a directory.

This function releases the chirp_dir object returned by chirp_reli_opendir. It should be called after chirp_reli_readdir returns null to indicate the end of the directory. Note that this function has no timeoutbecause it operates solely on memory structures.

Parameters

dir	A pointer to a directory returned from chirp_reli_opendir.

See Also: chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir

INT64_T chirp_reli_getacl	(	const char *	host,
		const char *	path,
		chirp_dir_t	callback,
		void *	arg,
		time_t	stoptime
	)

Get an access control list.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
callback	A function to call for each entry of the ACL.
arg	An additional argument to pass to the callback.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_setacl	(	const char *	host,
		const char *	path,
		const char *	subject,
		const char *	rights,
		time_t	stoptime
	)

Modify an access control list.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
subject	The name of the subject to modify, such as `"hostname:somewhere.nd.edu"`.
rights	A string giving the new rights for the subject, such as `"rwlda"` or `"."` to indicate no rights.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

Referenced by chirp.Client::setacl().

INT64_T chirp_reli_resetacl	(	const char *	host,
		const char *	path,
		const char *	rights,
		time_t	stoptime
	)

Reset an access control list.

This call will remove all entries from the access control list and grant to the calling user only those rights stated here.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to access.
rights	A string giving the new rights for the subject, such as `"rwlda"`.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_locate	(	const char *	host,
		const char *	path,
		chirp_loc_t	callback,
		void *	arg,
		time_t	stoptime
	)

Identify the true location of a path.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to locate.
callback	A function to call for each location of the file.
arg	An additional argument to pass to the callback.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_whoami	(	const char *	host,
		char *	subject,
		INT64_T	length,
		time_t	stoptime
	)

Return the caller's identity.

Parameters

host	The name and port of the Chirp server to access.
subject	The buffer to fill with the caller's identity.
length	The length of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_whoareyou	(	const char *	host,
		const char *	rhost,
		char *	subject,
		INT64_T	length,
		time_t	stoptime
	)

Return the server's identity against another server.

This causes the server to call another Chirp server and invoke chirp_reli_whoami.

Parameters

host	The name and port of the Chirp server to access.
rhost	The name and port of the other server to connect to.
subject	The buffer to fill with the server's identity.
length	The length of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_unlink	(	const char *	host,
		const char *	path,
		time_t	stoptime
	)

Delete a file.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to delete.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_rename	(	const char *	host,
		const char *	path,
		const char *	newpath,
		time_t	stoptime
	)

Rename a file or directory.

Parameters

host	The name and port of the Chirp server to access.
path	The current pathname of the file.
newpath	The new pathname of the file.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_link	(	const char *	host,
		const char *	path,
		const char *	newpath,
		time_t	stoptime
	)

Create a hard link.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of an existing file.
newpath	The name of the link to create.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_symlink	(	const char *	host,
		const char *	path,
		const char *	newpath,
		time_t	stoptime
	)

Create a symbolic link.

Parameters

host	The name and port of the Chirp server to access.
path	The existing path to link to.
newpath	The name of the new link to create.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_readlink	(	const char *	host,
		const char *	path,
		char *	buf,
		INT64_T	length,
		time_t	stoptime
	)

Examine a symbolic link.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the link to read.
buf	The buffer in which to place the link contents.
length	The length of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_mkdir	(	const char *	host,
		const char *	path,
		INT64_T	mode,
		time_t	stoptime
	)

Create a new directory.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to create.
mode	The unix mode bits of the new directory, typically `0700`.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_mkdir_recursive	(	const char *	host,
		const char *	path,
		INT64_T	mode,
		time_t	stoptime
	)

Create a new directory recursively.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to create.
mode	The unix mode bits of the new directory, typically `0700`.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

Referenced by chirp.Client::mkdir().

INT64_T chirp_reli_rmdir	(	const char *	host,
		const char *	path,
		time_t	stoptime
	)

Delete a directory if it is empty.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to delete.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

See Also: chirp_reli_rmall.

INT64_T chirp_reli_rmall	(	const char *	host,
		const char *	path,
		time_t	stoptime
	)

Delete a directory recursively.

Deletes a directory recursively, even if it is not empty. The recursion is performed on the file server, so this call is efficient to perform over the network.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to delete.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno. @

Referenced by chirp.Client::rm().

INT64_T chirp_reli_stat	(	const char *	host,
		const char *	path,
		struct chirp_stat *	info,
		time_t	stoptime
	)

Get file status.

If called on a symbolic link, chirp_reli_stat will follow that link and obtain the status of the underlying file.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
info	A pointer to a chirp_stat structure to fill.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_lstat	(	const char *	host,
		const char *	path,
		struct chirp_stat *	info,
		time_t	stoptime
	)

Get file or link status.

If called on a symbolic link, chirp_reli_lstat will return the status of the link itself.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
info	A pointer to a chirp_stat structure to fill.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

See Also: chirp_reli_lstat, chirp_reli_fstat, chirp_reli_statfs

INT64_T chirp_reli_statfs	(	const char *	host,
		const char *	path,
		struct chirp_statfs *	info,
		time_t	stoptime
	)

Get filesystem status.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
info	A pointer to a chirp_statfs structure to fill.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_access	(	const char *	host,
		const char *	path,
		INT64_T	flags,
		time_t	stoptime
	)

Check access permissions.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
flags	Access permission to check: R_OK - Check for read permission. W_OK - Check for write permission. X_OK - Check for execute permission.
stoptime	The absolute time at which to abort.

Returns: If access will be granted, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_chmod	(	const char *	host,
		const char *	path,
		INT64_T	mode,
		time_t	stoptime
	)

Change mode bits.

The mode bits may set group/other permissions. If the file is a not a directory, the mode bits may also set user execute. See chirp_reli_setacl for alternate strong authorization control.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
mode	The new mode bits, typically `0700` for an executable or `0600` for a data file.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

See Also: chirp_reli_fchmod, chirp_reli_setacl

Referenced by chirp.Client::chmod().

INT64_T chirp_reli_chown	(	const char *	host,
		const char *	path,
		INT64_T	uid,
		INT64_T	gid,
		time_t	stoptime
	)

Change the ownership of a file.

Deprecated:: Note that the current Chirp file server does not make use of the Unix owner field, see chirp_reli_setacl instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
uid	The new user ID.
gid	The new group ID.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_fchown, chirp_reli_setacl, chirp_reli_getacl

INT64_T chirp_reli_lchown	(	const char *	host,
		const char *	path,
		INT64_T	uid,
		INT64_T	gid,
		time_t	stoptime
	)

Change the ownership of a file or link.

Deprecated:: Note that the current Chirp file server does not make use of the Unix owner field, see chirp_reli_setacl instead.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
uid	The new user ID.
gid	The new group ID.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_fchown, chirp_reli_setacl, chirp_reli_getacl

INT64_T chirp_reli_truncate	(	const char *	host,
		const char *	path,
		INT64_T	length,
		time_t	stoptime
	)

Truncate a file.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
length	The new length of the file.
stoptime	The absolute time at which to abort.

See Also: chirp_reli_ftruncate

INT64_T chirp_reli_utime	(	const char *	host,
		const char *	path,
		time_t	actime,
		time_t	modtime,
		time_t	stoptime
	)

Change the modification times of a file.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
actime	The new access time.
modtime	The new modification time.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_hash	(	const char *	host,
		const char *	path,
		const char *	algorithm,
		unsigned char	digest[CHIRP_DIGEST_MAX],
		time_t	stoptime
	)

Checksum a remote file.

A hash checksum is performed remotely by the file server, so it is much more efficient than pulling data and computing the hash locally. Note that the data is returned in binary digest form.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
algorithm	The type of hash function to use (e.g. "md5" or "sha1").
digest	The buffer to place the binary checksum digest.
stoptime	The absolute time at which to abort.

Returns: On success, returns actual size of the digest. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_md5	(	const char *	host,
		const char *	path,
		unsigned char	digest[CHIRP_DIGEST_MAX],
		time_t	stoptime
	)

Checksum a remote file.

(DEPRECATED: use chirp_reli_hash) This MD5 checksum is performed remotely by the file server, so it is much more efficient than computing one by invoking a local command. Note that the data is returned in binary digest form. Use md5_string to convert the digest into a human readable form.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
digest	The buffer to place the binary checksum digest.
stoptime	The absolute time at which to abort.

Returns: On success, returns length of digest. On failure, returns less than zero and sets errno.

See Also: md5_string

INT64_T chirp_reli_setrep	(	const char *	host,
		const char *	path,
		int	nreps,
		time_t	stoptime
	)

Set replication factor.

Sets the number of replicas desired for the indicated file or for all newly created files. This only has an effect if the server backend supports replication, currently only with HDFS.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to modify. If the pathname is `"@@@"`, then this call sets the replication factor for all files created by this process.
nreps	The number of replicas desired. Zero indicates the server should use the default replication value.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_remote_debug	(	const char *	host,
		const char *	flag,
		time_t	stoptime
	)

Set the debug options on the remote server.

Parameters

host	The name and port of the Chirp server to access.
flag	A debug flag to set on the server. Pass NULL to not change. Pass "clear" to clear.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_localpath	(	const char *	host,
		const char *	path,
		char *	localpath,
		int	length,
		time_t	stoptime
	)

Return the local path of a file.

This function allows the caller to find out the local path where a file is stored, which is useful if you intend to execute a program on the host by some other means to access the file. Note that the local path will only be accessible if the directory ACL has been readable to the user system:localuser using chirp_reli_setacl.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
localpath	A buffer into which the local path will be stored.
length	The length of the buffer in bytes.
stoptime	The absolute time at which to abort.

Returns: On success, greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_audit	(	const char *	host,
		const char *	path,
		struct chirp_audit **	list,
		time_t	stoptime
	)

Measure remote space consumption.

This routine causes the server to internally measure the space consumed by each user of the system. This could be a very long running function call. It then allocates a list of chirp_audit structures describing the current space usage. The caller is responsible for free()ing the list when done.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
list	A pointer to an uninitialized `struct chirp_audit *list`.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_thirdput	(	const char *	host,
		const char *	path,
		const char *	thirdhost,
		const char *	thirdpath,
		time_t	stoptime
	)

Third party transfer.

Directs the server to transfer a file or directory to another (third-party) server. If a directory is mentioned, the transfer will be performed recursively, and will preserve the access controls present in the source directory.

Parameters

host	The name and port of the source Chirp server.
path	The pathname of the source file or directory to transfer.
thirdhost	The name and port of the target Chirp server.
thirdpath	The pathname of the target file or directory.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

INT64_T chirp_reli_mkalloc	(	const char *	host,
		const char *	path,
		INT64_T	size,
		INT64_T	mode,
		time_t	stoptime
	)

Create a space allocation.

Creates a new directory with a firm guarantee that the user will be able to store a specific amount of data there.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the directory to create.
size	The size in bytes of the allocation.
mode	The unix mode bits of the new directory, typically `0700`.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

See Also: chirp_reli_lsalloc

INT64_T chirp_reli_lsalloc	(	const char *	host,
		const char *	path,
		char *	allocpath,
		INT64_T *	total,
		INT64_T *	inuse,
		time_t	stoptime
	)

List a space allocation.

Parameters

host	The name and port of the Chirp server to access.
path	The pathname of the file to access.
allocpath	A buffer that will be filled with the root path of the containing allocation.
total	A pointer to an INT64_T that will be filled with the total size of the allocation.
inuse	A pointer to an INT64_T that will be filled with the bytes actually used in the allocation.
stoptime	The absolute time at which to abort.

Returns: On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.

See Also: chirp_reli_mkalloc

INT64_T chirp_reli_bulkio	(	struct chirp_bulkio *	list,
		int	count,
		time_t	stoptime
	)

Perform multiple I/O operations in bulk.

This operation will perform multiple I/O operations by pipelining the requests and the results. It is the most efficient way to perform multiple reads and writes simultaneously, whether against one or many files.

Parameters

list	An array of chirp_bulkio structures, each describing one I/O operation.
count	The number of entries in the list.
stoptime	The absolute time at which to abort.

Returns: If all operations in the array succeed, this function will return greater than or equal to zero. If one or more operations fail, this function will return less than zero. The result of each individual operation may be determined by examining the result and errnum fields set in each chirp_bulkio structure.

INT64_T chirp_reli_blocksize_get ( )

Return the current buffer block size.

This module performs input and output buffering to improve the performance of small I/O operations. Operations larger than the buffer size are sent directly over the network, while those smaller are aggregated together. This function returns the current buffer size.

Returns: The current file buffer size.

void chirp_reli_blocksize_set ( INT64_T bs )

Set the buffer block size.

This module performs input and output buffering to improve the performance of small I/O operations. Operations larger than the buffer size are sent directly over the network, while those smaller are aggregated together. This function sets the current buffer size.

Parameters

bs	The new buffer block size.

void chirp_reli_cleanup_before_fork ( )

Prepare to fork in a parallel program.

The Chirp library is not thread-safe, but it can be used in a program that exploits parallelism by calling fork(). Before calling fork, this function must be invoked to clean up shared state such as TCP connections. After forking, each process will maintain its own connection to each Chirp server.

void chirp_reli_disconnect ( const char * host )

Closes the link to the host, if active.

Parameters

host	A hostname may be a domain name or an IP address, followed by an optional colon and port number.

Referenced by chirp.Client::__init__().

Functions

Detailed Description

Function Documentation