2
Copyright (C) 2003-2004 Douglas Thain and the University of Wisconsin
3
Copyright (C) 2005- The University of Notre Dame
4
This software is distributed under the GNU General Public License.
5
See the file COPYING for details.
8
/** @file chirp_reli.h The primary user API for accessing Chirp servers.
10
@ref chirp_reli.h is designed to look similar to the Unix I/O interface.
11
It is called "reli" because it is "reliable".
12
Each function call here has the capabaility to detect and retry a large number
13
of network and server errors with an exponential backoff, until a user-defined time limit is reached.
14
The caller need not worry about connecting to or disconnecting from servers.
16
All functions in this file have several common calling conventions.
17
@param host A hostname may be a domain name or an IP address, followed by an optional colon and port number.
18
If not given, the port number is assumed to by the default Chirp port of 9094.
19
@param path A pathname identifies a file from the root of the given file server, and must start with a slash.
20
The Chirp protocol allows pathnames to contain any printable ASCII character except a newline.
21
@param stoptime All functions accept a final argument <tt>time_t stoptime</tt> which
22
indicates the absolute time at which to abort. For example, to
23
try an operation for 60 seconds, pass <tt>time(0)+60</tt> as <tt>stoptime</tt>.
24
Any transient network failures will be silently retried until this timeout is reached.
25
@return On success, all functions return an integer <b>greater than or equal to zero</b>,
26
and <tt>errno</tt> may have any arbitrary value.
27
On failure, all return an integer <b>less than zero</b>, and set errno
28
to the reason for the failure. (@ref chirp_reli_open is the only exception to this rule.)
29
The caller may invoke <tt>strerror(errno)</tt> to generate a human-readable string representing the error.
35
#include "chirp_types.h"
37
#include <sys/types.h>
40
/** Creates or opens a file in preparation for I/O.
41
@param host The name and port of the Chirp server to access.
42
@param path The pathname of the file to access.
43
@param flags Any of the following Unix open flags ORed together:
44
- O_RDONLY - Open for reading only.
45
- O_WRONLY - Open for writing only.
46
- O_RDWR - Open for both read and write.
47
- O_APPEND - Open for appending to the file.
48
- O_CREAT - Create the file if it does not exist.
49
- O_TRUNC - Truncate the file to zero bytes.
50
- O_SYNC - Force synchronous writes to disk.
51
@param mode The Unix mode bits to be given to the file. Chirp only honors the owner component of the mode bits. Typical choices
52
are <tt>0700</tt> for an executable, and <tt>0600</tt> for a data file. (Note the leading zero to indicate octal data.)
53
@param stoptime The absolute time at which to abort.
54
@return On success, returns a pointer to a chirp_file. On failure, returns zero and sets errno appropriately.
55
@see 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
58
struct chirp_file * chirp_reli_open( const char *host, const char *path, INT64_T flags, INT64_T mode, time_t stoptime );
60
/** Closes an open file. Note that a close may need to write buffered data to disk before completing, so <b>chirp_reli_close can fail</b>.
61
If chirp_reli_close indicates failures, the <tt>struct chirp_file</tt> is deallocated and can no longer be used, but the caller
62
must assume some previously written data was lost.
63
@param file A chirp_file handle returned by chirp_reli_open.
64
@param stoptime The absolute time at which to abort.
68
INT64_T chirp_reli_close( struct chirp_file *file, time_t stoptime );
70
/** Read data from a file. Small reads may be buffered into large reads for efficiency.
71
@param file A chirp_file handle returned by chirp_reli_open.
72
@param buffer Pointer to destination buffer.
73
@param length Number of bytes to read.
74
@param offset Beginning offset in file.
75
@param stoptime The absolute time at which to abort.
76
@return 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.
77
@see chirp_reli_open, chirp_reli_pread_unbuffered, chirp_reli_sread
80
INT64_T chirp_reli_pread( struct chirp_file *file, void *buffer, INT64_T length, INT64_T offset, time_t stoptime );
82
/** Write data to a file. Small writes may be buffered together into large writes for efficiency.
83
@param file A chirp_file handle returned by chirp_reli_open.
84
@param buffer Pointer to source buffer.
85
@param length Number of bytes to write.
86
@param offset Beginning offset in file.
87
@param stoptime The absolute time at which to abort.
88
@return On success, returns the number of bytes actually written, which may be less than requested. On failure, <0 and sets errno.
89
@param stoptime The absolute time at which to abort.
90
@see chirp_reli_open, chirp_reli_swrite
93
INT64_T chirp_reli_pwrite( struct chirp_file *file, const void *buffer, INT64_T length, INT64_T offset, time_t stoptime );
95
/** Read data from a file without buffering.
96
@param file A chirp_file handle returned by chirp_reli_open.
97
@param buffer Pointer to destination buffer.
98
@param length Number of bytes to read.
99
@param offset Beginning offset in file.
100
@param stoptime The absolute time at which to abort.
101
@return 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.
102
@see chirp_reli_open, chirp_reli_pread, chirp_reli_sread
105
INT64_T chirp_reli_pread_unbuffered( struct chirp_file *file, void *buffer, INT64_T length, INT64_T offset, time_t stoptime );
107
/** Write data to a file without buffering.
108
@param file A chirp_file handle returned by chirp_reli_open.
109
@param buffer Pointer to source buffer.
110
@param length Number of bytes to write.
111
@param offset Beginning offset in file.
112
@param stoptime The absolute time at which to abort.
113
@return On success, returns the number of bytes actually written. On failure, <0 and sets errno.
114
@see chirp_reli_open, chirp_reli_pwrite, chirp_reli_swrite
117
INT64_T chirp_reli_pwrite_unbuffered( struct chirp_file *file, const void *buffer, INT64_T length, INT64_T offset, time_t stoptime );
119
/** Strided read from a file. Reads <tt>stride_length</tt> bytes every <tt>stride_skip</tt> bytes, starting from <tt>offset</tt>
120
up to a maximum of <tt>length</tt> bytes read.
121
@param file A chirp_file handle returned by chirp_reli_open.
122
@param buffer Pointer to destiation buffer.
123
@param length Maximum number of bytes to read.
124
@param stride_length Bytes to read in each stride.
125
@param stride_skip Bytes to skip between each stride.
126
@param offset Beginning offset in file.
127
@param stoptime The absolute time at which to abort.
128
@return On success, returns the number of bytes actually read, which may be less than requested. On failure, <0 and sets errno.
129
@param stoptime The absolute time at which to abort.
130
@see chirp_reli_open, chirp_reli_pread, chirp_reli_pwrite, chirp_reli_sread, chirp_reli_swrite
133
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 );
135
/** Strided write to a file. Writes <tt>stride_length</tt> bytes every <tt>stride_skip</tt> bytes, starting from <tt>offset</tt>
136
up to a maximum of <tt>length</tt> bytes written.
137
@param file A chirp_file handle returned by chirp_reli_open.
138
@param buffer Pointer to destiation buffer.
139
@param length Maximum number of bytes to write.
140
@param stride_length Bytes to write in each stride.
141
@param stride_skip Bytes to skip between each stride.
142
@param offset Beginning offset in file.
143
@param stoptime The absolute time at which to abort.
144
@return On success, returns the number of bytes actually written, which may be less than requested. On failure, <0 and sets errno.
145
@param stoptime The absolute time at which to abort.
146
@see chirp_reli_open, chirp_reli_pread, chirp_reli_pwrite, chirp_reli_sread, chirp_reli_swrite
149
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 );
152
@param file A chirp_file handle returned by chirp_reli_open.
153
@param info A pointer to a @ref chirp_stat structure to fill.
154
@param stoptime The absolute time at which to abort.
155
@return >=0 on success, <0 on failure.
156
@see chirp_reli_open, chirp_stat
159
INT64_T chirp_reli_fstat( struct chirp_file *file, struct chirp_stat *info, time_t stoptime );
161
/** Get file system status.
162
@param file A chirp_file handle returned by chirp_reli_open.
163
@param info A pointer to a @ref chirp_statfs structure to fill.
164
@param stoptime The absolute time at which to abort.
165
@return >=0 on success, <0 on failure.
166
@see chirp_reli_open, chirp_reli_statfs
169
INT64_T chirp_reli_fstatfs( struct chirp_file *file, struct chirp_statfs *info, time_t stoptime );
171
/** Change the ownership of a file.
172
@deprecated Note that the current Chirp file server does not make use of the Unix owner field, see @ref chirp_reli_setacl instead.
173
@param file A chirp_file handle returned by chirp_reli_open.
174
@param uid The new user ID.
175
@param gid The new group ID.
176
@param stoptime The absolute time at which to abort.
177
@see chirp_reli_chown, chirp_reli_setacl, chirp_reli_getacl
180
INT64_T chirp_reli_fchown( struct chirp_file *file, INT64_T uid, INT64_T gid, time_t stoptime );
182
/** Change the mode bits of a file.
183
Note that the current Chirp file server ignores the mode bits,
184
except to determine whether a program is executable. See @ref chirp_reli_setacl instead.
185
@param file A chirp_file handle returned by chirp_reli_open.
186
@param mode The new mode bits, typically <tt>0700</tt> for an executable or <tt>0600</tt> for a data file.
187
@param stoptime The absolute time at which to abort.
188
@see chirp_reli_chmod, chirp_reli_setacl, chirp_reli_getacl
191
INT64_T chirp_reli_fchmod( struct chirp_file *file, INT64_T mode, time_t stoptime );
193
/** Truncate an open file.
194
@param file A chirp_file handle returned by chirp_reli_open.
195
@param length The new length of the file.
196
@param stoptime The absolute time at which to abort.
197
@see chirp_reli_open, chirp_reli_truncate
200
INT64_T chirp_reli_ftruncate( struct chirp_file *file, INT64_T length, time_t stoptime );
202
/** Flush any pending changes to a file.
203
To improve performance, Chirp buffers small writes to files.
204
These writes might not be forced to disk until a later write or a call to @ref chirp_reli_close.
205
To force any buffered writes to disk, call this function.
206
@param file A chirp_file handle returned by chirp_reli_open.
207
@param stoptime The absolute time at which to abort.
208
@see chirp_reli_close
211
INT64_T chirp_reli_flush( struct chirp_file *file, time_t stoptime );
213
INT64_T chirp_reli_fsync( struct chirp_file *file, time_t stoptime );
215
/** Get an entire file efficiently.
216
Reads an entire remote file, and write the contents to a standard FILE stream.
217
To get an entire directory tree, see @ref chirp_recursive_get instead.
218
@param host The name and port of the Chirp server to access.
219
@param path The pathname of the file to access.
220
@param stream A standard FILE stream obtained from fopen(). Such a stream may be obtained from fopen(), or could be the standard globals
221
<tt>stdin</tt>, <tt>stdout</tt>, or <tt>stderr</tt>.
222
@param stoptime The absolute time at which to abort.
223
@return The size in bytes of the file, or less than zero on error.
227
INT64_T chirp_reli_getfile( const char *host, const char *path, FILE *stream, time_t stoptime );
229
/** Get an entire file efficiently to memory.
230
Reads an entire remote file into newly allocated memory.
231
To get an entire directory tree, see @ref chirp_recursive_get instead.
232
@param host The name and port of the Chirp server to access.
233
@param path The pathname of the file to access.
234
@param buffer A pointer to an uninitialized pointer.
235
On success, this pointer will point to newly allocated memory containing the file. The caller must then release the member by calling free().
236
@param stoptime The absolute time at which to abort.
237
@return The size of the file in bytes, or less than zero on error.
240
INT64_T chirp_reli_getfile_buffer( const char *host, const char *path, char **buffer, time_t stoptime );
242
/** Put an entire file efficiently.
243
Reads data out of a standard I/O stream and writes it to a remote file.
244
To put an entire directory tree, see @ref chirp_recursive_put instead.
245
@param host The name and port of the Chirp server to access.
246
@param path The pathname of the file to access.
247
@param stream A standard FILE stream obtained from fopen(). Such a stream may be obtained from fopen(), or could be the standard globals
248
<tt>stdin</tt>, <tt>stdout</tt>, or <tt>stderr</tt>.
249
@param mode The Unix mode bits to give to the remote file, typically <tt>0700</tt> for an executable or <tt>0600</tt> for a data file.
250
@param length The length in bytes of the file to write.
251
@param stoptime The absolute time at which to abort.
252
@return The size of the file in bytes, or less than zero on error.
255
INT64_T chirp_reli_putfile( const char *host, const char *path, FILE *stream, INT64_T mode, INT64_T length, time_t stoptime );
257
/** Put an entire file efficiently from memory.
258
Reads data out of memory and writes it to a remote file.
259
To put an entire directory tree, see @ref chirp_recursive_put instead.
260
@param host The name and port of the Chirp server to access.
261
@param path The pathname of the file to access.
262
@param buffer A pointer to the file data to write.
263
@param mode The Unix mode bits to give to the remote file, typically <tt>0700</tt> for an executable or <tt>0600</tt> for a data file.
264
@param length The length in bytes of the file to write.
265
@param stoptime The absolute time at which to abort.
266
@return The size of the file in bytes, or less than zero on error.
269
INT64_T chirp_reli_putfile_buffer( const char *host, const char *path, const char *buffer, INT64_T mode, INT64_T length, time_t stoptime );
271
/** Get a detailed directory listing.
272
Gets a detailed directory listing from a Chirp server, and then calls the callback once for each element in the directory.
273
@param host The name and port of the Chirp server to access.
274
@param path The pathname of the directory to access.
275
@param callback The function to be called for each element in the listing.
276
@param arg An optional convenience pointer that will be passed to the callback function.
277
@param stoptime The absolute time at which to abort.
278
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
281
INT64_T chirp_reli_getlongdir( const char *host, const char *path, chirp_longdir_t callback, void *arg, time_t stoptime );
283
/** Get a simple directory listing.
284
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 @ref chirp_reli_opendir easier to use.
285
@param host The name and port of the Chirp server to access.
286
@param path The pathname of the directory to access.
287
@param callback The function to be called for each element in the listing.
288
@param arg An optional convenience pointer that will be passed to the callback function.
289
@param stoptime The absolute time at which to abort.
290
@see chirp_reli_opendir
291
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
294
INT64_T chirp_reli_getdir( const char *host, const char *path, chirp_dir_t callback, void *arg, time_t stoptime );
296
/** Get an access control list.
297
Gets an access control list from a Chirp server, and then calls the callback once for each element in the list.
298
This is a low-level function, you may find @ref chirp_reli_opendir easier to use.
299
@param host The name and port of the Chirp server to access.
300
@param path The pathname of the directory to access.
301
@param callback The function to be called for each element in the listing.
302
@param arg An optional convenience pointer that will be passed to the callback function.
303
@param stoptime The absolute time at which to abort.
304
@see chirp_reli_opendir
305
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
309
Open a directory for listing. This function returns a pointer to an opened directory.
310
You may then call @ref chirp_reli_readdir to read directory elements one by one.
311
@param host The name and port of the Chirp server to access.
312
@param path The pathname of the directory to access.
313
@param stoptime The absolute time at which to abort.
314
@return On success, returns a pointer to an opaque chirp_dir object. On failure, returns null.
315
@see chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir
318
struct chirp_dir * chirp_reli_opendir( const char *host, const char *path, time_t stoptime );
321
Read one item from a directory. Accepts a pointer to a directory opened by @ref chirp_reli_opendir
322
and returns the next @ref chirp_dirent object, which describes the name and properties of the next
323
item in the list. Returns null when the list is complete.
324
Note that this function has no timeout because it operates solely on memory structures.
325
@param dir A pointer to a directory returned from @ref chirp_reli_opendir.
326
@return On success, returns a pointer to a @ref chirp_dirent object. Returns null when the list is complete.
327
@see chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir
330
struct chirp_dirent * chirp_reli_readdir( struct chirp_dir *dir );
333
Close a directory. This function releases the chirp_dir object returned by @ref chirp_reli_opendir.
334
It should be called after @ref chirp_reli_readdir returns null to indicate the end of the directory.
335
Note that this function has no timeoutbecause it operates solely on memory structures.
336
@param dir A pointer to a directory returned from @ref chirp_reli_opendir.
337
@see chirp_reli_opendir chirp_reli_readdir, chirp_reli_closedir
340
void chirp_reli_closedir( struct chirp_dir *dir );
343
INT64_T chirp_reli_ticket_create( const char *host, char name[CHIRP_PATH_MAX], unsigned bits, time_t stoptime );
344
INT64_T chirp_reli_ticket_register( const char *host, const char *name, const char *subject, time_t duration, time_t stoptime );
345
INT64_T chirp_reli_ticket_delete( const char *host, const char *name, time_t stoptime );
346
INT64_T chirp_reli_ticket_list( const char *host, const char *subject, char ***list, time_t stoptime );
347
INT64_T chirp_reli_ticket_get( const char *host, const char *name, char **subject, char **ticket, time_t *duration, char ***rights, time_t stoptime );
348
INT64_T chirp_reli_ticket_modify( const char *host, const char *name, const char *path, const char *aclmask, time_t stoptime );
350
/** Get an access control list.
351
@param host The name and port of the Chirp server to access.
352
@param path The pathname of the directory to access.
353
@param callback A function to call for each entry of the ACL.
354
@param arg An additional argument to pass to the callback.
355
@param stoptime The absolute time at which to abort.
356
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
359
INT64_T chirp_reli_getacl( const char *host, const char *path, chirp_dir_t callback, void *arg, time_t stoptime );
361
/** Modify an access control list.
362
@param host The name and port of the Chirp server to access.
363
@param path The pathname of the directory to access.
364
@param subject The name of the subject to modify, such as <tt>"hostname:somewhere.nd.edu"</tt>.
365
@param rights A string giving the new rights for the subject, such as <tt>"rwlda"</tt> or <tt>"."</tt> to indicate no rights.
366
@param stoptime The absolute time at which to abort.
367
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
370
INT64_T chirp_reli_setacl( const char *host, const char *path, const char *subject, const char *rights, time_t stoptime );
372
/** 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.
373
@param host The name and port of the Chirp server to access.
374
@param path The pathname of the directory to access.
375
@param rights A string giving the new rights for the subject, such as <tt>"rwlda"</tt>.
376
@param stoptime The absolute time at which to abort.
377
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
380
INT64_T chirp_reli_resetacl( const char *host, const char *path, const char *rights, time_t stoptime );
382
/** Identify the true location of a path.
383
@param host The name and port of the Chirp server to access.
384
@param path The pathname of the file to locate.
385
@param callback A function to call for each location of the file.
386
@param arg An additional argument to pass to the callback.
387
@param stoptime The absolute time at which to abort.
388
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
390
INT64_T chirp_reli_locate( const char *host, const char *path, chirp_loc_t callback, void *arg, time_t stoptime );
392
/** Return the caller's identity.
393
@param host The name and port of the Chirp server to access.
394
@param subject The buffer to fill with the caller's identity.
395
@param length The length of the buffer in bytes.
396
@param stoptime The absolute time at which to abort.
397
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
400
INT64_T chirp_reli_whoami( const char *host, char *subject, INT64_T length, time_t stoptime );
402
/** Return the server's identity against another server.
403
This causes the server to call <b>another</b> Chirp server and invoke @ref chirp_reli_whoami.
404
@param host The name and port of the Chirp server to access.
405
@param rhost The name and port of the other server to connect to.
406
@param subject The buffer to fill with the server's identity.
407
@param length The length of the buffer in bytes.
408
@param stoptime The absolute time at which to abort.
409
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
412
INT64_T chirp_reli_whoareyou( const char *host, const char *rhost, char *subject, INT64_T length, time_t stoptime );
414
/** Create a named pipe (FIFO).
415
A named pipe (FIFO) is a rendezvous that appears as a file.
416
Programs that read from the named pipe will block until another program connects and issues a write.
417
@param host The name and port of the Chirp server to access.
418
@param path The pathname of the FIFO to create.
419
@param stoptime The absolute time at which to abort.
420
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
423
INT64_T chirp_reli_mkfifo( const char *host, const char *path, time_t stoptime );
426
@param host The name and port of the Chirp server to access.
427
@param path The pathname of the file to delete.
428
@param stoptime The absolute time at which to abort.
429
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
432
INT64_T chirp_reli_unlink( const char *host, const char *path, time_t stoptime );
434
/** Rename a file or directory.
435
@param host The name and port of the Chirp server to access.
436
@param path The current pathname of the file.
437
@param newpath The new pathname of the file.
438
@param stoptime The absolute time at which to abort.
439
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
442
INT64_T chirp_reli_rename( const char *host, const char *path, const char *newpath, time_t stoptime );
444
/** Create a hard link.
445
@param host The name and port of the Chirp server to access.
446
@param path The pathname of an existing file.
447
@param newpath The name of the link to create.
448
@param stoptime The absolute time at which to abort.
449
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
452
INT64_T chirp_reli_link( const char *host, const char *path, const char *newpath, time_t stoptime );
454
/** Create a symbolic link.
455
@param host The name and port of the Chirp server to access.
456
@param path The existing path to link to.
457
@param newpath The name of the new link to create.
458
@param stoptime The absolute time at which to abort.
459
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
462
INT64_T chirp_reli_symlink( const char *host, const char *path, const char *newpath, time_t stoptime );
464
/** Examine a symbolic link.
465
@param host The name and port of the Chirp server to access.
466
@param path The pathname of the link to read.
467
@param buf The buffer in which to place the link contents.
468
@param length The length of the buffer in bytes.
469
@param stoptime The absolute time at which to abort.
470
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
473
INT64_T chirp_reli_readlink( const char *host, const char *path, char *buf, INT64_T length, time_t stoptime );
476
/** Create a new directory.
477
@param host The name and port of the Chirp server to access.
478
@param path The pathname of the directory to create.
479
@param mode The unix mode bits of the new directory, typically <tt>0700</tt>.
480
@param stoptime The absolute time at which to abort.
481
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
484
INT64_T chirp_reli_mkdir( const char *host, const char *path, INT64_T mode, time_t stoptime );
486
/** Create a new directory recursively.
487
@param host The name and port of the Chirp server to access.
488
@param path The pathname of the directory to create.
489
@param mode The unix mode bits of the new directory, typically <tt>0700</tt>.
490
@param stoptime The absolute time at which to abort.
491
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
494
INT64_T chirp_reli_mkdir_recursive( const char *host, const char *path, INT64_T mode, time_t stoptime );
496
/** Delete a directory if it is empty.
497
@param host The name and port of the Chirp server to access.
498
@param path The pathname of the directory to delete.
499
@param stoptime The absolute time at which to abort.
500
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
501
@see chirp_reli_rmall.
504
INT64_T chirp_reli_rmdir( const char *host, const char *path, time_t stoptime );
506
/** Delete a directory recursively.
507
Deletes a directory recursively, even if it is not empty.
508
The recursion is performed on the file server, so this call is efficient to perform over the network.
509
@param host The name and port of the Chirp server to access.
510
@param path The pathname of the directory to delete.
511
@param stoptime The absolute time at which to abort.
512
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
516
INT64_T chirp_reli_rmall( const char *host, const char *path, time_t stoptime );
519
If called on a symbolic link, @ref chirp_reli_stat will follow that link and obtain the status of the underlying file.
520
@param host The name and port of the Chirp server to access.
521
@param path The pathname of the file to access.
522
@param info A pointer to a @ref chirp_stat structure to fill.
523
@param stoptime The absolute time at which to abort.
524
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
527
INT64_T chirp_reli_stat( const char *host, const char *path, struct chirp_stat *info, time_t stoptime );
529
/** Get file or link status.
530
If called on a symbolic link, @ref chirp_reli_lstat will return the status of the link itself.
531
@param host The name and port of the Chirp server to access.
532
@param path The pathname of the file to access.
533
@param info A pointer to a @ref chirp_stat structure to fill.
534
@param stoptime The absolute time at which to abort.
535
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
536
@see chirp_reli_lstat, chirp_reli_fstat, chirp_reli_statfs
539
INT64_T chirp_reli_lstat( const char *host, const char *path, struct chirp_stat *info, time_t stoptime );
541
/** Get filesystem status.
542
@param host The name and port of the Chirp server to access.
543
@param path The pathname of the file to access.
544
@param info A pointer to a @ref chirp_statfs structure to fill.
545
@param stoptime The absolute time at which to abort.
546
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
549
INT64_T chirp_reli_statfs( const char *host, const char *path, struct chirp_statfs *info, time_t stoptime );
551
/** Check access permissions.
552
@param host The name and port of the Chirp server to access.
553
@param path The pathname of the file to access.
554
@param flags Access permission to check:
555
- R_OK - Check for read permission.
556
- W_OK - Check for write permission.
557
- X_OK - Check for execute permission.
558
@param stoptime The absolute time at which to abort.
559
@return If access will be granted, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
562
INT64_T chirp_reli_access( const char *host, const char *path, INT64_T flags, time_t stoptime );
564
/** Change mode bits.
565
Note that the current Chirp file server ignores the mode bits,
566
except to determine whether a program is executable. See @ref chirp_reli_setacl instead.
567
@param host The name and port of the Chirp server to access.
568
@param path The pathname of the file to access.
569
@param mode The new mode bits, typically <tt>0700</tt> for an executable or <tt>0600</tt> for a data file.
570
@param stoptime The absolute time at which to abort.
571
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
572
@see chirp_reli_fchmod, chirp_reli_setacl
575
INT64_T chirp_reli_chmod( const char *host, const char *path, INT64_T mode, time_t stoptime );
577
/** Change the ownership of a file.
578
@deprecated Note that the current Chirp file server does not make use of the Unix owner field, see @ref chirp_reli_setacl instead.
579
@param host The name and port of the Chirp server to access.
580
@param path The pathname of the file to access.
581
@param uid The new user ID.
582
@param gid The new group ID.
583
@param stoptime The absolute time at which to abort.
584
@see chirp_reli_fchown, chirp_reli_setacl, chirp_reli_getacl
587
INT64_T chirp_reli_chown( const char *host, const char *path, INT64_T uid, INT64_T gid, time_t stoptime );
589
/** Change the ownership of a file or link.
590
@deprecated Note that the current Chirp file server does not make use of the Unix owner field, see @ref chirp_reli_setacl instead.
591
@param host The name and port of the Chirp server to access.
592
@param path The pathname of the file to access.
593
@param uid The new user ID.
594
@param gid The new group ID.
595
@param stoptime The absolute time at which to abort.
596
@see chirp_reli_fchown, chirp_reli_setacl, chirp_reli_getacl
599
INT64_T chirp_reli_lchown( const char *host, const char *path, INT64_T uid, INT64_T gid, time_t stoptime );
602
@param host The name and port of the Chirp server to access.
603
@param path The pathname of the file to access.
604
@param length The new length of the file.
605
@param stoptime The absolute time at which to abort.
606
@see chirp_reli_ftruncate
609
INT64_T chirp_reli_truncate( const char *host, const char *path, INT64_T length, time_t stoptime );
611
/** Change the modification times of a file.
612
@param host The name and port of the Chirp server to access.
613
@param path The pathname of the file to access.
614
@param actime The new access time.
615
@param modtime The new modification time.
616
@param stoptime The absolute time at which to abort.
617
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
620
INT64_T chirp_reli_utime( const char *host, const char *path, time_t actime, time_t modtime, time_t stoptime );
622
/** Checksum a remote file.
623
This MD5 checksum is performed remotely by the file server, so it is much more
624
efficient than computing one by invoking a local command. Note that the data
625
is returned in <b>binary</b> digest form. Use @ref md5_string to convert the
626
digest into a human readable form.
627
@param host The name and port of the Chirp server to access.
628
@param path The pathname of the file to access.
629
@param digest The buffer to place the binary checksum digest.
630
@param stoptime The absolute time at which to abort.
631
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
635
INT64_T chirp_reli_md5( const char *host, const char *path, unsigned char digest[16], time_t stoptime );
637
/** Return the local path of a file.
638
This function allows the caller to find out the local path where a file is stored,
639
which is useful if you intend to execute a program on the host by some other means to access the file.
640
Note that the local path will only be accessible if the directory ACL
641
has been readable to the user <tt>system:localuser</tt> using @ref chirp_reli_setacl.
642
@param host The name and port of the Chirp server to access.
643
@param path The pathname of the file to access.
644
@param localpath A buffer into which the local path will be stored.
645
@param length The length of the buffer in bytes.
646
@param stoptime The absolute time at which to abort.
647
@return On success, greater than or equal to zero. On failure, returns less than zero and sets errno.
650
INT64_T chirp_reli_localpath( const char *host, const char *path, char *localpath, int length, time_t stoptime );
652
/** Measure remote space consumption.
653
This routine causes the server to internally measure the space consumed by each user of the system.
654
This could be a very long running function call. It then allocates a list of @ref chirp_audit structures
655
describing the current space usage. The caller is responsible for free()ing the list when done.
656
@param host The name and port of the Chirp server to access.
657
@param path The pathname of the file to access.
658
@param list A pointer to an uninitialized <tt>struct chirp_audit *list</tt>.
659
@param stoptime The absolute time at which to abort.
660
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
663
INT64_T chirp_reli_audit( const char *host, const char *path, struct chirp_audit **list, time_t stoptime );
665
/** Third party transfer.
666
Directs the server to transfer a file or directory to another (third-party) server.
667
If a directory is mentioned, the transfer will be performed recursively, and will
668
preserve the access controls present in the source directory.
669
@param host The name and port of the source Chirp server.
670
@param path The pathname of the source file or directory to transfer.
671
@param thirdhost The name and port of the target Chirp server.
672
@param thirdpath The pathname of the target file or directory.
673
@param stoptime The absolute time at which to abort.
674
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
677
INT64_T chirp_reli_thirdput( const char *host, const char *path, const char *thirdhost, const char *thirdpath, time_t stoptime );
679
/** Create a space allocation.
680
Creates a new directory with a firm guarantee that the user will be able to store a specific amount of data there.
681
@param host The name and port of the Chirp server to access.
682
@param path The pathname of the directory to create.
683
@param size The size in bytes of the allocation.
684
@param mode The unix mode bits of the new directory, typically <tt>0700</tt>.
685
@param stoptime The absolute time at which to abort.
686
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
687
@see chirp_reli_lsalloc
690
INT64_T chirp_reli_mkalloc( const char *host, const char *path, INT64_T size, INT64_T mode, time_t stoptime );
692
/** List a space allocation.
693
@param host The name and port of the Chirp server to access.
694
@param path The pathname of the file to access.
695
@param allocpath A buffer that will be filled with the root path of the containing allocation.
696
@param total A pointer to an INT64_T that will be filled with the total size of the allocation.
697
@param inuse A pointer to an INT64_T that will be filled with the bytes actually used in the allocation.
698
@param stoptime The absolute time at which to abort.
699
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
700
@see chirp_reli_mkalloc
703
INT64_T chirp_reli_lsalloc( const char *host, const char *path, char *allocpath, INT64_T *total, INT64_T *inuse, time_t stoptime );
705
/** Create a new access control group.
706
Note that group is deleted by calling @ref chirp_reli_unlink on the group name.
707
@param host The name and port of the server hosting the group.
708
@param group The group name, which is simply a path on the server.
709
@param stoptime The absolute time at which to abort.
710
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
713
INT64_T chirp_reli_group_create( const char *host, char *group, time_t stoptime );
715
/** List members of an access control group.
716
@param host The name and port of the server hosting the group.
717
@param group The group name, which is simple a path on the server.
718
@param callback A function to call for each member of the group.
719
@param arg An optional convenience pointer to pass to the callback.
720
@param stoptime The absolute time at which to abort.
721
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
724
INT64_T chirp_reli_group_list( const char *host, const char *group, chirp_dir_t callback, void *arg, time_t stoptime );
726
/** Add a user to a group.
727
@param host The name and port of the server hosting the group.
728
@param group The group name, which is simple a path on the server.
729
@param user The subject name to add to the group.
730
@param stoptime The absolute time at which to abort.
731
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
734
INT64_T chirp_reli_group_add( const char *host, char *group, char *user, time_t stoptime );
736
/** Remove a user from a group.
737
@param host The name and port of the server hosting the group.
738
@param group The group name, which is simple a path on the server.
739
@param user The subject name to remove from the group.
740
@param stoptime The absolute time at which to abort.
741
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
744
INT64_T chirp_reli_group_remove( const char *host, char *group, char *user, time_t stoptime );
746
/** Test membership in a group.
747
@param host The name and port of the server hosting the group.
748
@param group The group name, which is simple a path on the server.
749
@param user The subject name to remove from the group.
750
@param stoptime The absolute time at which to abort.
751
@return Greater than zero if the user is a member of the group, zero is the user is not a member of a group, less than zero if there is a failure to access the group.
754
INT64_T chirp_reli_group_lookup( const char *host, const char *group, const char *user, time_t stoptime );
756
/* Note that these functions are not documented because they are only used for inter-server communications. */
757
INT64_T chirp_reli_group_cache_update( const char *host, const char *group, time_t mod_time, time_t stoptime );
758
INT64_T chirp_reli_group_policy_set( const char *host, char *group, unsigned long int file_duration, unsigned long int dec_duration, time_t stoptime );
759
INT64_T chirp_reli_group_policy_get( const char *host, const char *group, int *policy, int *file_duration, int *dec_duration, time_t stoptime );
761
/** Create a new active storage job.
762
This function creates a new job with a given command line and the explicitly names the current working directory and standard I/O files.
763
A unique job identifier will be returned, which must be given to @ref chirp_reli_job_commit, which will permit the job to run.
764
@param host The name and port of the Chirp server to access.
765
@param cwd The initial working directory of the job.
766
@param input A file to use as the standard input stream, or "-" for none.
767
@param output A file to use as the standard output stream, or "-" for none.
768
@param error A file to use as the standard error stream, or "-" for none.
769
@param cmdline The command line to execute, beginning with the path of the executable.
770
@param stoptime The absolute time at which to abort.
771
@return On success, returns a unique job identifier. On failure, returns less than zero and sets errno.
772
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
775
INT64_T chirp_reli_job_begin( const char *host, const char *cwd, const char *input, const char *output, const char *error, const char *cmdline, time_t stoptime );
777
/** Commit an active storage job.
778
A job created by @ref chirp_reli_job_begin is not allowed to run until it is committed by calling @ref chirp_reli_job_commit.
779
This is called a <i>two phase commit</i> and is necessary to prevent runaway jobs of which the caller does not know the job ID.
780
After this function is called, the job is free to run within the constraints of the local scheduler.
781
@param host The name and port of the Chirp server to access.
782
@param jobid The job identifier.
783
@param stoptime The absolute time at which to abort.
784
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
785
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
788
INT64_T chirp_reli_job_commit( const char *host, INT64_T jobid, time_t stoptime );
790
/** Get status of an active storage job.
791
This function will obtain the detailed status of an active storage job, optionally waiting until it is complete.
792
If wait_time is zero, then the job's status will be immediately returned.
793
If wait_time is greater than zero, then this function will wait until the job reaches a completed state,
794
or the wait_time expires.
795
<b>Note that stoptime must be greater than waittime, otherwise you will never receive a response.</b>
796
@param host The name and port of the Chirp server to access.
797
@param jobid The job identifier.
798
@param state A pointer to a buffer to be filled with the job's current states.
799
@param wait_time The maximum time to wait for the job to complete.
800
@param stoptime The absolute time at which to abort.
801
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
802
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
805
INT64_T chirp_reli_job_wait( const char *host, INT64_T jobid, struct chirp_job_state *state, int wait_time, time_t stoptime );
807
/** Kill an active storage job.
808
Forces the named job into the @ref CHIRP_JOB_STATE_KILLED state.
809
The job record must still be removed by calling @ref chirp_reli_job_remove.
810
The caller must be the owner of this job.
811
@param host The name and port of the Chirp server to access.
812
@param jobid The job identifier.
813
@param stoptime The absolute time at which to abort.
814
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
815
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
818
INT64_T chirp_reli_job_kill( const char *host, INT64_T jobid, time_t stoptime );
820
/** Remove an active storage job.
821
Deletes the record and all other state associated with an active storage job.
822
If the job is not yet complete, it will be killed first.
823
The caller must be the owner of this job.
824
@param host The name and port of the Chirp server to access.
825
@param jobid The job identifier.
826
@param stoptime The absolute time at which to abort.
827
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
828
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
831
INT64_T chirp_reli_job_remove( const char *host, INT64_T jobid, time_t stoptime );
833
/** List all active storage jobs.
834
Returns status about all known jobs on a server, regardless of their owner or state.
835
@param host The name and port of the Chirp server to access.
836
@param callback The function to be called for each job in the listing.
837
@param arg An optional convenience pointer passed to the callback.
838
@param stoptime The absolute time at which to abort.
839
@return On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno.
840
@see chirp_reli_job_begin, chirp_reli_job_commit, chirp_reli_job_wait, chirp_reli_job_list, chirp_reli_job_kill, chirp_reli_job_remove
843
INT64_T chirp_reli_job_list( const char *host, chirp_joblist_t callback, void *arg, time_t stoptime );
845
/** Perform multiple I/O operations simultaneously.
846
This call invokes any number of I/O operations simultaneously,
847
using pipelining and parallelism to complete quickly.
848
Multiple operations may affect a single host, multiple hosts,
849
or a mix of the two. The list of operations is given by
850
an array of @ref chirp_bulkio structures, each of which specifies
851
an individual operation from @ref chirp_reli.h. Note that only
852
a select few operations are available through this interface.
853
Future versions of the API may be more complete.
854
@param list The list of operations to be performed.
855
@param count The number of entries in list.
856
@param stoptime The absolute time at which to abort.
857
@returns On success, returns greater than or equal to zero. On failure, returns less than zero and sets errno appropriately. Note that "success" means all the operations were successfully dispatched. Each individual operation will have it success or failure and errno recorded in the corresponding @ref chirp_bulkio structure.
860
INT64_T chirp_reli_bulkio( struct chirp_bulkio *list, int count, time_t stoptime );
862
/** Return the current buffer block size.
863
This module performs input and output buffering to improve the performance of small I/O operations.
864
Operations larger than the buffer size are sent directly over the network, while those smaller are
865
aggregated together. This function returns the current buffer size.
866
@return The current file buffer size.
869
INT64_T chirp_reli_blocksize_get();
871
/** Set the buffer block size.
872
This module performs input and output buffering to improve the performance of small I/O operations.
873
Operations larger than the buffer size are sent directly over the network, while those smaller are
874
aggregated together. This function sets the current buffer size.
875
@param bs The new buffer block size.
878
void chirp_reli_blocksize_set( INT64_T bs );
880
/** Prepare to fork in a parallel program.
881
The Chirp library is not thread-safe, but it can be used in a program
882
that exploits parallelism by calling fork(). Before calling fork, this
883
function must be invoked to clean up shared state such as TCP connections.
884
After forking, each process will maintain its own connection to each Chirp server.
887
void chirp_reli_cleanup_before_fork();
added
removed
chirp/src/chirp_reli.h
