1 | /******************************************************************** |
2 | * Copyright (c) 2013 - 2014, Pivotal Inc. |
3 | * All rights reserved. |
4 | * |
5 | * Author: Zhanwei Wang |
6 | ********************************************************************/ |
7 | /******************************************************************** |
8 | * 2014 - |
9 | * open source under Apache License Version 2.0 |
10 | ********************************************************************/ |
11 | /** |
12 | * Licensed to the Apache Software Foundation (ASF) under one |
13 | * or more contributor license agreements. See the NOTICE file |
14 | * distributed with this work for additional information |
15 | * regarding copyright ownership. The ASF licenses this file |
16 | * to you under the Apache License, Version 2.0 (the |
17 | * "License"); you may not use this file except in compliance |
18 | * with the License. You may obtain a copy of the License at |
19 | * |
20 | * http://www.apache.org/licenses/LICENSE-2.0 |
21 | * |
22 | * Unless required by applicable law or agreed to in writing, software |
23 | * distributed under the License is distributed on an "AS IS" BASIS, |
24 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
25 | * See the License for the specific language governing permissions and |
26 | * limitations under the License. |
27 | */ |
28 | #ifndef _HDFS_LIBHDFS3_CLIENT_HDFS_H_ |
29 | #define _HDFS_LIBHDFS3_CLIENT_HDFS_H_ |
30 | |
31 | #include <errno.h> /* for EINTERNAL, etc. */ |
32 | #include <fcntl.h> /* for O_RDONLY, O_WRONLY */ |
33 | #include <stdint.h> /* for uint64_t, etc. */ |
34 | #include <time.h> /* for time_t */ |
35 | |
36 | #ifndef O_RDONLY |
37 | #define O_RDONLY 1 |
38 | #endif |
39 | |
40 | #ifndef O_WRONLY |
41 | #define O_WRONLY 2 |
42 | #endif |
43 | |
44 | #ifndef EINTERNAL |
45 | #define EINTERNAL 255 |
46 | #endif |
47 | |
48 | /** All APIs set errno to meaningful values */ |
49 | |
50 | #ifdef __cplusplus |
51 | extern "C" { |
52 | #endif |
53 | /** |
54 | * Some utility decls used in libhdfs. |
55 | */ |
56 | typedef int32_t tSize; /// size of data for read/write io ops |
57 | typedef time_t tTime; /// time type in seconds |
58 | typedef int64_t tOffset; /// offset within the file |
59 | typedef uint16_t tPort; /// port |
60 | |
61 | typedef enum tObjectKind { |
62 | kObjectKindFile = 'F', kObjectKindDirectory = 'D', |
63 | } tObjectKind; |
64 | |
65 | struct HdfsFileSystemInternalWrapper; |
66 | typedef struct HdfsFileSystemInternalWrapper * hdfsFS; |
67 | |
68 | struct HdfsFileInternalWrapper; |
69 | typedef struct HdfsFileInternalWrapper * hdfsFile; |
70 | |
71 | struct hdfsBuilder; |
72 | |
73 | /** |
74 | * Return error information of last failed operation. |
75 | * |
76 | * @return A not NULL const string point of last error information. |
77 | * Caller can only read this message and keep it unchanged. No need to free it. |
78 | * If last operation finished successfully, the returned message is undefined. |
79 | */ |
80 | const char * hdfsGetLastError(); |
81 | |
82 | /** |
83 | * Determine if a file is open for read. |
84 | * |
85 | * @param file The HDFS file |
86 | * @return 1 if the file is open for read; 0 otherwise |
87 | */ |
88 | int hdfsFileIsOpenForRead(hdfsFile file); |
89 | |
90 | /** |
91 | * Determine if a file is open for write. |
92 | * |
93 | * @param file The HDFS file |
94 | * @return 1 if the file is open for write; 0 otherwise |
95 | */ |
96 | int hdfsFileIsOpenForWrite(hdfsFile file); |
97 | |
98 | /** |
99 | * hdfsConnectAsUser - Connect to a hdfs file system as a specific user |
100 | * Connect to the hdfs. |
101 | * @param nn The NameNode. See hdfsBuilderSetNameNode for details. |
102 | * @param port The port on which the server is listening. |
103 | * @param user the user name (this is hadoop domain user). Or NULL is equivelant to hhdfsConnect(host, port) |
104 | * @return Returns a handle to the filesystem or NULL on error. |
105 | * @deprecated Use hdfsBuilderConnect instead. |
106 | */ |
107 | hdfsFS hdfsConnectAsUser(const char * nn, tPort port, const char * user); |
108 | |
109 | /** |
110 | * hdfsConnect - Connect to a hdfs file system. |
111 | * Connect to the hdfs. |
112 | * @param nn The NameNode. See hdfsBuilderSetNameNode for details. |
113 | * @param port The port on which the server is listening. |
114 | * @return Returns a handle to the filesystem or NULL on error. |
115 | * @deprecated Use hdfsBuilderConnect instead. |
116 | */ |
117 | hdfsFS hdfsConnect(const char * nn, tPort port); |
118 | |
119 | /** |
120 | * hdfsConnect - Connect to an hdfs file system. |
121 | * |
122 | * Forces a new instance to be created |
123 | * |
124 | * @param nn The NameNode. See hdfsBuilderSetNameNode for details. |
125 | * @param port The port on which the server is listening. |
126 | * @param user The user name to use when connecting |
127 | * @return Returns a handle to the filesystem or NULL on error. |
128 | * @deprecated Use hdfsBuilderConnect instead. |
129 | */ |
130 | hdfsFS hdfsConnectAsUserNewInstance(const char * nn, tPort port, |
131 | const char * user); |
132 | |
133 | /** |
134 | * hdfsConnect - Connect to an hdfs file system. |
135 | * |
136 | * Forces a new instance to be created |
137 | * |
138 | * @param nn The NameNode. See hdfsBuilderSetNameNode for details. |
139 | * @param port The port on which the server is listening. |
140 | * @return Returns a handle to the filesystem or NULL on error. |
141 | * @deprecated Use hdfsBuilderConnect instead. |
142 | */ |
143 | hdfsFS hdfsConnectNewInstance(const char * nn, tPort port); |
144 | |
145 | /** |
146 | * Connect to HDFS using the parameters defined by the builder. |
147 | * |
148 | * The HDFS builder will be freed, whether or not the connection was |
149 | * successful. |
150 | * |
151 | * Every successful call to hdfsBuilderConnect should be matched with a call |
152 | * to hdfsDisconnect, when the hdfsFS is no longer needed. |
153 | * |
154 | * @param bld The HDFS builder |
155 | * @return Returns a handle to the filesystem, or NULL on error. |
156 | */ |
157 | hdfsFS hdfsBuilderConnect(struct hdfsBuilder * bld); |
158 | |
159 | /** |
160 | * Create an HDFS builder. |
161 | * |
162 | * @return The HDFS builder, or NULL on error. |
163 | */ |
164 | struct hdfsBuilder * hdfsNewBuilder(void); |
165 | |
166 | /** |
167 | * Do nothing, we always create a new instance |
168 | * |
169 | * @param bld The HDFS builder |
170 | */ |
171 | void hdfsBuilderSetForceNewInstance(struct hdfsBuilder * bld); |
172 | |
173 | /** |
174 | * Set the HDFS NameNode to connect to. |
175 | * |
176 | * @param bld The HDFS builder |
177 | * @param nn The NameNode to use. |
178 | * |
179 | * If the string given is 'default', the default NameNode |
180 | * configuration will be used (from the XML configuration files) |
181 | * |
182 | * If NULL is given, a LocalFileSystem will be created. |
183 | * |
184 | * If the string starts with a protocol type such as file:// or |
185 | * hdfs://, this protocol type will be used. If not, the |
186 | * hdfs:// protocol type will be used. |
187 | * |
188 | * You may specify a NameNode port in the usual way by |
189 | * passing a string of the format hdfs://<hostname>:<port>. |
190 | * Alternately, you may set the port with |
191 | * hdfsBuilderSetNameNodePort. However, you must not pass the |
192 | * port in two different ways. |
193 | */ |
194 | void hdfsBuilderSetNameNode(struct hdfsBuilder * bld, const char * nn); |
195 | |
196 | /** |
197 | * Set the port of the HDFS NameNode to connect to. |
198 | * |
199 | * @param bld The HDFS builder |
200 | * @param port The port. |
201 | */ |
202 | void hdfsBuilderSetNameNodePort(struct hdfsBuilder * bld, tPort port); |
203 | |
204 | /** |
205 | * Set the username to use when connecting to the HDFS cluster. |
206 | * |
207 | * @param bld The HDFS builder |
208 | * @param userName The user name. The string will be shallow-copied. |
209 | */ |
210 | void hdfsBuilderSetUserName(struct hdfsBuilder * bld, const char * userName); |
211 | |
212 | /** |
213 | * Set the path to the Kerberos ticket cache to use when connecting to |
214 | * the HDFS cluster. |
215 | * |
216 | * @param bld The HDFS builder |
217 | * @param kerbTicketCachePath The Kerberos ticket cache path. The string |
218 | * will be shallow-copied. |
219 | */ |
220 | void hdfsBuilderSetKerbTicketCachePath(struct hdfsBuilder * bld, |
221 | const char * kerbTicketCachePath); |
222 | |
223 | /** |
224 | * Set the token used to authenticate |
225 | * |
226 | * @param bld The HDFS builder |
227 | * @param token The token used to authenticate |
228 | */ |
229 | void hdfsBuilderSetToken(struct hdfsBuilder * bld, const char * token); |
230 | |
231 | /** |
232 | * Free an HDFS builder. |
233 | * |
234 | * It is normally not necessary to call this function since |
235 | * hdfsBuilderConnect frees the builder. |
236 | * |
237 | * @param bld The HDFS builder |
238 | */ |
239 | void hdfsFreeBuilder(struct hdfsBuilder * bld); |
240 | |
241 | /** |
242 | * Set a configuration string for an HdfsBuilder. |
243 | * |
244 | * @param key The key to set. |
245 | * @param val The value, or NULL to set no value. |
246 | * This will be shallow-copied. You are responsible for |
247 | * ensuring that it remains valid until the builder is |
248 | * freed. |
249 | * |
250 | * @return 0 on success; nonzero error code otherwise. |
251 | */ |
252 | int hdfsBuilderConfSetStr(struct hdfsBuilder * bld, const char * key, |
253 | const char * val); |
254 | |
255 | /** |
256 | * Get a configuration string. |
257 | * |
258 | * @param key The key to find |
259 | * @param val (out param) The value. This will be set to NULL if the |
260 | * key isn't found. You must free this string with |
261 | * hdfsConfStrFree. |
262 | * |
263 | * @return 0 on success; nonzero error code otherwise. |
264 | * Failure to find the key is not an error. |
265 | */ |
266 | int hdfsConfGetStr(const char * key, char ** val); |
267 | |
268 | /** |
269 | * Get a configuration integer. |
270 | * |
271 | * @param key The key to find |
272 | * @param val (out param) The value. This will NOT be changed if the |
273 | * key isn't found. |
274 | * |
275 | * @return 0 on success; nonzero error code otherwise. |
276 | * Failure to find the key is not an error. |
277 | */ |
278 | int hdfsConfGetInt(const char * key, int32_t * val); |
279 | |
280 | /** |
281 | * Free a configuration string found with hdfsConfGetStr. |
282 | * |
283 | * @param val A configuration string obtained from hdfsConfGetStr |
284 | */ |
285 | void hdfsConfStrFree(char * val); |
286 | |
287 | /** |
288 | * hdfsDisconnect - Disconnect from the hdfs file system. |
289 | * Disconnect from hdfs. |
290 | * @param fs The configured filesystem handle. |
291 | * @return Returns 0 on success, -1 on error. |
292 | * Even if there is an error, the resources associated with the |
293 | * hdfsFS will be freed. |
294 | */ |
295 | int hdfsDisconnect(hdfsFS fs); |
296 | |
297 | /** |
298 | * hdfsOpenFile - Open a hdfs file in given mode. |
299 | * @param fs The configured filesystem handle. |
300 | * @param path The full path to the file. |
301 | * @param flags - an | of bits/fcntl.h file flags - supported flags are O_RDONLY, O_WRONLY (meaning create or overwrite i.e., implies O_TRUNCAT), |
302 | * O_WRONLY|O_APPEND and O_SYNC. Other flags are generally ignored other than (O_RDWR || (O_EXCL & O_CREAT)) which return NULL and set errno equal ENOTSUP. |
303 | * @param bufferSize Size of buffer for read/write - pass 0 if you want |
304 | * to use the default configured values. |
305 | * @param replication Block replication - pass 0 if you want to use |
306 | * the default configured values. |
307 | * @param blocksize Size of block - pass 0 if you want to use the |
308 | * default configured values. |
309 | * @return Returns the handle to the open file or NULL on error. |
310 | */ |
311 | hdfsFile hdfsOpenFile(hdfsFS fs, const char * path, int flags, int bufferSize, |
312 | short replication, tOffset blocksize); |
313 | |
314 | /** |
315 | * hdfsCloseFile - Close an open file. |
316 | * @param fs The configured filesystem handle. |
317 | * @param file The file handle. |
318 | * @return Returns 0 on success, -1 on error. |
319 | * On error, errno will be set appropriately. |
320 | * If the hdfs file was valid, the memory associated with it will |
321 | * be freed at the end of this call, even if there was an I/O |
322 | * error. |
323 | */ |
324 | int hdfsCloseFile(hdfsFS fs, hdfsFile file); |
325 | |
326 | /** |
327 | * hdfsExists - Checks if a given path exsits on the filesystem |
328 | * @param fs The configured filesystem handle. |
329 | * @param path The path to look for |
330 | * @return Returns 0 on success, -1 on error. |
331 | */ |
332 | int hdfsExists(hdfsFS fs, const char * path); |
333 | |
334 | /** |
335 | * hdfsSeek - Seek to given offset in file. |
336 | * This works only for files opened in read-only mode. |
337 | * @param fs The configured filesystem handle. |
338 | * @param file The file handle. |
339 | * @param desiredPos Offset into the file to seek into. |
340 | * @return Returns 0 on success, -1 on error. |
341 | */ |
342 | int hdfsSeek(hdfsFS fs, hdfsFile file, tOffset desiredPos); |
343 | |
344 | /** |
345 | * hdfsTell - Get the current offset in the file, in bytes. |
346 | * @param fs The configured filesystem handle. |
347 | * @param file The file handle. |
348 | * @return Current offset, -1 on error. |
349 | */ |
350 | tOffset hdfsTell(hdfsFS fs, hdfsFile file); |
351 | |
352 | /** |
353 | * hdfsRead - Read data from an open file. |
354 | * @param fs The configured filesystem handle. |
355 | * @param file The file handle. |
356 | * @param buffer The buffer to copy read bytes into. |
357 | * @param length The length of the buffer. |
358 | * @return On success, a positive number indicating how many bytes |
359 | * were read. |
360 | * On end-of-file, 0. |
361 | * On error, -1. Errno will be set to the error code. |
362 | * Just like the POSIX read function, hdfsRead will return -1 |
363 | * and set errno to EINTR if data is temporarily unavailable, |
364 | * but we are not yet at the end of the file. |
365 | */ |
366 | tSize hdfsRead(hdfsFS fs, hdfsFile file, void * buffer, tSize length); |
367 | |
368 | /** |
369 | * hdfsWrite - Write data into an open file. |
370 | * @param fs The configured filesystem handle. |
371 | * @param file The file handle. |
372 | * @param buffer The data. |
373 | * @param length The no. of bytes to write. |
374 | * @return Returns the number of bytes written, -1 on error. |
375 | */ |
376 | tSize hdfsWrite(hdfsFS fs, hdfsFile file, const void * buffer, tSize length); |
377 | |
378 | /** |
379 | * hdfsWrite - Flush the data. |
380 | * @param fs The configured filesystem handle. |
381 | * @param file The file handle. |
382 | * @return Returns 0 on success, -1 on error. |
383 | */ |
384 | int hdfsFlush(hdfsFS fs, hdfsFile file); |
385 | |
386 | /** |
387 | * hdfsHFlush - Flush out the data in client's user buffer. After the |
388 | * return of this call, new readers will see the data. |
389 | * @param fs configured filesystem handle |
390 | * @param file file handle |
391 | * @return 0 on success, -1 on error and sets errno |
392 | */ |
393 | int hdfsHFlush(hdfsFS fs, hdfsFile file); |
394 | |
395 | /** |
396 | * hdfsSync - Flush out and sync the data in client's user buffer. After the |
397 | * return of this call, new readers will see the data. |
398 | * @param fs configured filesystem handle |
399 | * @param file file handle |
400 | * @return 0 on success, -1 on error and sets errno |
401 | */ |
402 | int hdfsSync(hdfsFS fs, hdfsFile file); |
403 | |
404 | /** |
405 | * hdfsAvailable - Number of bytes that can be read from this |
406 | * input stream without blocking. |
407 | * @param fs The configured filesystem handle. |
408 | * @param file The file handle. |
409 | * @return Returns available bytes; -1 on error. |
410 | */ |
411 | int hdfsAvailable(hdfsFS fs, hdfsFile file); |
412 | |
413 | /** |
414 | * hdfsCopy - Copy file from one filesystem to another. |
415 | * @param srcFS The handle to source filesystem. |
416 | * @param src The path of source file. |
417 | * @param dstFS The handle to destination filesystem. |
418 | * @param dst The path of destination file. |
419 | * @return Returns 0 on success, -1 on error. |
420 | */ |
421 | int hdfsCopy(hdfsFS srcFS, const char * src, hdfsFS dstFS, const char * dst); |
422 | |
423 | /** |
424 | * hdfsMove - Move file from one filesystem to another. |
425 | * @param srcFS The handle to source filesystem. |
426 | * @param src The path of source file. |
427 | * @param dstFS The handle to destination filesystem. |
428 | * @param dst The path of destination file. |
429 | * @return Returns 0 on success, -1 on error. |
430 | */ |
431 | int hdfsMove(hdfsFS srcFS, const char * src, hdfsFS dstFS, const char * dst); |
432 | |
433 | /** |
434 | * hdfsDelete - Delete file. |
435 | * @param fs The configured filesystem handle. |
436 | * @param path The path of the file. |
437 | * @param recursive if path is a directory and set to |
438 | * non-zero, the directory is deleted else throws an exception. In |
439 | * case of a file the recursive argument is irrelevant. |
440 | * @return Returns 0 on success, -1 on error. |
441 | */ |
442 | int hdfsDelete(hdfsFS fs, const char * path, int recursive); |
443 | |
444 | /** |
445 | * hdfsRename - Rename file. |
446 | * @param fs The configured filesystem handle. |
447 | * @param oldPath The path of the source file. |
448 | * @param newPath The path of the destination file. |
449 | * @return Returns 0 on success, -1 on error. |
450 | */ |
451 | int hdfsRename(hdfsFS fs, const char * oldPath, const char * newPath); |
452 | |
453 | /** |
454 | * hdfsGetWorkingDirectory - Get the current working directory for |
455 | * the given filesystem. |
456 | * @param fs The configured filesystem handle. |
457 | * @param buffer The user-buffer to copy path of cwd into. |
458 | * @param bufferSize The length of user-buffer. |
459 | * @return Returns buffer, NULL on error. |
460 | */ |
461 | char * hdfsGetWorkingDirectory(hdfsFS fs, char * buffer, size_t bufferSize); |
462 | |
463 | /** |
464 | * hdfsSetWorkingDirectory - Set the working directory. All relative |
465 | * paths will be resolved relative to it. |
466 | * @param fs The configured filesystem handle. |
467 | * @param path The path of the new 'cwd'. |
468 | * @return Returns 0 on success, -1 on error. |
469 | */ |
470 | int hdfsSetWorkingDirectory(hdfsFS fs, const char * path); |
471 | |
472 | /** |
473 | * hdfsCreateDirectory - Make the given file and all non-existent |
474 | * parents into directories. |
475 | * @param fs The configured filesystem handle. |
476 | * @param path The path of the directory. |
477 | * @return Returns 0 on success, -1 on error. |
478 | */ |
479 | int hdfsCreateDirectory(hdfsFS fs, const char * path); |
480 | |
481 | /** |
482 | * hdfsSetReplication - Set the replication of the specified |
483 | * file to the supplied value |
484 | * @param fs The configured filesystem handle. |
485 | * @param path The path of the file. |
486 | * @return Returns 0 on success, -1 on error. |
487 | */ |
488 | int hdfsSetReplication(hdfsFS fs, const char * path, int16_t replication); |
489 | |
490 | /** |
491 | * hdfsFileInfo - Information about a file/directory. |
492 | */ |
493 | typedef struct { |
494 | tObjectKind mKind; /* file or directory */ |
495 | char * mName; /* the name of the file */ |
496 | tTime mLastMod; /* the last modification time for the file in seconds */ |
497 | tOffset mSize; /* the size of the file in bytes */ |
498 | short mReplication; /* the count of replicas */ |
499 | tOffset mBlockSize; /* the block size for the file */ |
500 | char * mOwner; /* the owner of the file */ |
501 | char * mGroup; /* the group associated with the file */ |
502 | short mPermissions; /* the permissions associated with the file */ |
503 | tTime mLastAccess; /* the last access time for the file in seconds */ |
504 | } hdfsFileInfo; |
505 | |
506 | /** |
507 | * hdfsListDirectory - Get list of files/directories for a given |
508 | * directory-path. hdfsFreeFileInfo should be called to deallocate memory. |
509 | * @param fs The configured filesystem handle. |
510 | * @param path The path of the directory. |
511 | * @param numEntries Set to the number of files/directories in path. |
512 | * @return Returns a dynamically-allocated array of hdfsFileInfo |
513 | * objects; NULL on error. |
514 | */ |
515 | hdfsFileInfo * hdfsListDirectory(hdfsFS fs, const char * path, int * numEntries); |
516 | |
517 | /** |
518 | * hdfsGetPathInfo - Get information about a path as a (dynamically |
519 | * allocated) single hdfsFileInfo struct. hdfsFreeFileInfo should be |
520 | * called when the pointer is no longer needed. |
521 | * @param fs The configured filesystem handle. |
522 | * @param path The path of the file. |
523 | * @return Returns a dynamically-allocated hdfsFileInfo object; |
524 | * NULL on error. |
525 | */ |
526 | hdfsFileInfo * hdfsGetPathInfo(hdfsFS fs, const char * path); |
527 | |
528 | /** |
529 | * hdfsFreeFileInfo - Free up the hdfsFileInfo array (including fields) |
530 | * @param infos The array of dynamically-allocated hdfsFileInfo |
531 | * objects. |
532 | * @param numEntries The size of the array. |
533 | */ |
534 | void hdfsFreeFileInfo(hdfsFileInfo * infos, int numEntries); |
535 | |
536 | /** |
537 | * hdfsGetHosts - Get hostnames where a particular block (determined by |
538 | * pos & blocksize) of a file is stored. The last element in the array |
539 | * is NULL. Due to replication, a single block could be present on |
540 | * multiple hosts. |
541 | * @param fs The configured filesystem handle. |
542 | * @param path The path of the file. |
543 | * @param start The start of the block. |
544 | * @param length The length of the block. |
545 | * @return Returns a dynamically-allocated 2-d array of blocks-hosts; |
546 | * NULL on error. |
547 | */ |
548 | char ***hdfsGetHosts(hdfsFS fs, const char *path, tOffset start, |
549 | tOffset length); |
550 | |
551 | /** |
552 | * hdfsFreeHosts - Free up the structure returned by hdfsGetHosts |
553 | * @param hdfsFileInfo The array of dynamically-allocated hdfsFileInfo |
554 | * objects. |
555 | * @param numEntries The size of the array. |
556 | */ |
557 | void hdfsFreeHosts(char ***blockHosts); |
558 | |
559 | /** |
560 | * hdfsGetDefaultBlockSize - Get the default blocksize. |
561 | * |
562 | * @param fs The configured filesystem handle. |
563 | * @deprecated Use hdfsGetDefaultBlockSizeAtPath instead. |
564 | * |
565 | * @return Returns the default blocksize, or -1 on error. |
566 | */ |
567 | tOffset hdfsGetDefaultBlockSize(hdfsFS fs); |
568 | |
569 | /** |
570 | * hdfsGetCapacity - Return the raw capacity of the filesystem. |
571 | * @param fs The configured filesystem handle. |
572 | * @return Returns the raw-capacity; -1 on error. |
573 | */ |
574 | tOffset hdfsGetCapacity(hdfsFS fs); |
575 | |
576 | /** |
577 | * hdfsGetUsed - Return the total raw size of all files in the filesystem. |
578 | * @param fs The configured filesystem handle. |
579 | * @return Returns the total-size; -1 on error. |
580 | */ |
581 | tOffset hdfsGetUsed(hdfsFS fs); |
582 | |
583 | /** |
584 | * Change the user and/or group of a file or directory. |
585 | * |
586 | * @param fs The configured filesystem handle. |
587 | * @param path the path to the file or directory |
588 | * @param owner User string. Set to NULL for 'no change' |
589 | * @param group Group string. Set to NULL for 'no change' |
590 | * @return 0 on success else -1 |
591 | */ |
592 | int hdfsChown(hdfsFS fs, const char * path, const char * owner, |
593 | const char * group); |
594 | |
595 | /** |
596 | * hdfsChmod |
597 | * @param fs The configured filesystem handle. |
598 | * @param path the path to the file or directory |
599 | * @param mode the bitmask to set it to |
600 | * @return 0 on success else -1 |
601 | */ |
602 | int hdfsChmod(hdfsFS fs, const char * path, short mode); |
603 | |
604 | /** |
605 | * hdfsUtime |
606 | * @param fs The configured filesystem handle. |
607 | * @param path the path to the file or directory |
608 | * @param mtime new modification time or -1 for no change |
609 | * @param atime new access time or -1 for no change |
610 | * @return 0 on success else -1 |
611 | */ |
612 | int hdfsUtime(hdfsFS fs, const char * path, tTime mtime, tTime atime); |
613 | |
614 | /** |
615 | * hdfsTruncate - Truncate the file in the indicated path to the indicated size. |
616 | * @param fs The configured filesystem handle. |
617 | * @param path the path to the file. |
618 | * @param pos the position the file will be truncated to. |
619 | * @param shouldWait output value, true if and client does not need to wait for block recovery, |
620 | * false if client needs to wait for block recovery. |
621 | */ |
622 | int hdfsTruncate(hdfsFS fs, const char * path, tOffset pos, int * shouldWait); |
623 | |
624 | /** |
625 | * Get a delegation token from namenode. |
626 | * The token should be freed using hdfsFreeDelegationToken after canceling the token or token expired. |
627 | * |
628 | * @param fs The file system |
629 | * @param renewer The user who will renew the token |
630 | * |
631 | * @return Return a delegation token, NULL on error. |
632 | */ |
633 | char * hdfsGetDelegationToken(hdfsFS fs, const char * renewer); |
634 | |
635 | /** |
636 | * Free a delegation token. |
637 | * |
638 | * @param token The token to be freed. |
639 | */ |
640 | void hdfsFreeDelegationToken(char * token); |
641 | |
642 | /** |
643 | * Renew a delegation token. |
644 | * |
645 | * @param fs The file system. |
646 | * @param token The token to be renewed. |
647 | * |
648 | * @return the new expiration time |
649 | */ |
650 | int64_t hdfsRenewDelegationToken(hdfsFS fs, const char * token); |
651 | |
652 | /** |
653 | * Cancel a delegation token. |
654 | * |
655 | * @param fs The file system. |
656 | * @param token The token to be canceled. |
657 | * |
658 | * @return return 0 on success, -1 on error. |
659 | */ |
660 | int hdfsCancelDelegationToken(hdfsFS fs, const char * token); |
661 | |
662 | typedef struct Namenode { |
663 | char * rpc_addr; // namenode rpc address and port, such as "host:9000" |
664 | char * http_addr; // namenode http address and port, such as "host:50070" |
665 | } Namenode; |
666 | |
667 | /** |
668 | * If hdfs is configured with HA namenode, return all namenode informations as an array. |
669 | * Else return NULL. |
670 | * |
671 | * Using configure file which is given by environment parameter LIBHDFS3_CONF |
672 | * or "hdfs-client.xml" in working directory. |
673 | * |
674 | * @param nameservice hdfs name service id. |
675 | * @param size output the size of returning array. |
676 | * |
677 | * @return return an array of all namenode information. |
678 | */ |
679 | Namenode * hdfsGetHANamenodes(const char * nameservice, int * size); |
680 | |
681 | /** |
682 | * If hdfs is configured with HA namenode, return all namenode informations as an array. |
683 | * Else return NULL. |
684 | * |
685 | * @param conf the path of configure file. |
686 | * @param nameservice hdfs name service id. |
687 | * @param size output the size of returning array. |
688 | * |
689 | * @return return an array of all namenode information. |
690 | */ |
691 | Namenode * hdfsGetHANamenodesWithConfig(const char * conf, const char * nameservice, int * size); |
692 | |
693 | /** |
694 | * Free the array returned by hdfsGetConfiguredNamenodes() |
695 | * |
696 | * @param the array return by hdfsGetConfiguredNamenodes() |
697 | */ |
698 | void hdfsFreeNamenodeInformation(Namenode * namenodes, int size); |
699 | |
700 | typedef struct BlockLocation { |
701 | int corrupt; // If the block is corrupt |
702 | int numOfNodes; // Number of Datanodes which keep the block |
703 | char ** hosts; // Datanode hostnames |
704 | char ** names; // Datanode IP:xferPort for accessing the block |
705 | char ** topologyPaths; // Full path name in network topology |
706 | tOffset length; // block length, may be 0 for the last block |
707 | tOffset offset; // Offset of the block in the file |
708 | } BlockLocation; |
709 | |
710 | /** |
711 | * Get an array containing hostnames, offset and size of portions of the given file. |
712 | * |
713 | * @param fs The file system |
714 | * @param path The path to the file |
715 | * @param start The start offset into the given file |
716 | * @param length The length for which to get locations for |
717 | * @param numOfBlock Output the number of elements in the returned array |
718 | * |
719 | * @return An array of BlockLocation struct. |
720 | */ |
721 | BlockLocation * hdfsGetFileBlockLocations(hdfsFS fs, const char * path, |
722 | tOffset start, tOffset length, int * numOfBlock); |
723 | |
724 | /** |
725 | * Free the BlockLocation array returned by hdfsGetFileBlockLocations |
726 | * |
727 | * @param locations The array returned by hdfsGetFileBlockLocations |
728 | * @param numOfBlock The number of elements in the locaitons |
729 | */ |
730 | void hdfsFreeFileBlockLocations(BlockLocation * locations, int numOfBlock); |
731 | |
732 | #ifdef __cplusplus |
733 | } |
734 | #endif |
735 | |
736 | #endif /* _HDFS_LIBHDFS3_CLIENT_HDFS_H_ */ |
737 | |