folly/FileUtil.h

   1 /*
   2  * Copyright 2013 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef FOLLY_FILEUTIL_H_
  18 #define FOLLY_FILEUTIL_H_
  19
  20 #include "folly/Portability.h"
  21
  22 #include <sys/stat.h>
  23 #include <sys/types.h>
  24 #include <sys/uio.h>
  25 #include <fcntl.h>
  26 #include <unistd.h>
  27
  28 namespace folly {
  29
  30 /**
  31  * Convenience wrappers around some commonly used system calls.  The *NoInt
  32  * wrappers retry on EINTR.  The *Full wrappers retry on EINTR and also loop
  33  * until all data is written.  Note that *Full wrappers weaken the thread
  34  * semantics of underlying system calls.
  35  */
  36 int openNoInt(const char* name, int flags, mode_t mode=0644);
  37 int closeNoInt(int fd);
  38 int fsyncNoInt(int fd);
  39 int fdatasyncNoInt(int fd);
  40 int ftruncateNoInt(int fd, off_t len);
  41 int truncateNoInt(const char* path, off_t len);
  42
  43 ssize_t readNoInt(int fd, void* buf, size_t n);
  44 ssize_t preadNoInt(int fd, void* buf, size_t n, off_t offset);
  45 ssize_t readvNoInt(int fd, const iovec* iov, int count);
  46
  47 ssize_t writeNoInt(int fd, const void* buf, size_t n);
  48 ssize_t pwriteNoInt(int fd, const void* buf, size_t n, off_t offset);
  49 ssize_t writevNoInt(int fd, const iovec* iov, int count);
  50
  51 /**
  52  * Wrapper around read() (and pread()) that, in addition to retrying on
  53  * EINTR, will loop until all data is read.
  54  *
  55  * This wrapper is only useful for blocking file descriptors (for non-blocking
  56  * file descriptors, you have to be prepared to deal with incomplete reads
  57  * anyway), and only exists because POSIX allows read() to return an incomplete
  58  * read if interrupted by a signal (instead of returning -1 and setting errno
  59  * to EINTR).
  60  *
  61  * Note that this wrapper weakens the thread safety of read(): the file pointer
  62  * is shared between threads, but the system call is atomic.  If multiple
  63  * threads are reading from a file at the same time, you don't know where your
  64  * data came from in the file, but you do know that the returned bytes were
  65  * contiguous.  You can no longer make this assumption if using readFull().
  66  * You should probably use pread() when reading from the same file descriptor
  67  * from multiple threads simultaneously, anyway.
  68  *
  69  * Note that readvFull and preadvFull require iov to be non-const, unlike
  70  * readv and preadv.  The contents of iov after these functions return
  71  * is unspecified.
  72  */
  73 ssize_t readFull(int fd, void* buf, size_t n);
  74 ssize_t preadFull(int fd, void* buf, size_t n, off_t offset);
  75 ssize_t readvFull(int fd, iovec* iov, int count);
  76 #ifdef FOLLY_HAVE_PREADV
  77 ssize_t preadvFull(int fd, iovec* iov, int count, off_t offset);
  78 #endif
  79
  80 /**
  81  * Similar to readFull and preadFull above, wrappers around write() and
  82  * pwrite() that loop until all data is written.
  83  *
  84  * Generally, the write() / pwrite() system call may always write fewer bytes
  85  * than requested, just like read().  In certain cases (such as when writing to
  86  * a pipe), POSIX provides stronger guarantees, but not in the general case.
  87  * For example, Linux (even on a 64-bit platform) won't write more than 2GB in
  88  * one write() system call.
  89  *
  90  * Note that writevFull and pwritevFull require iov to be non-const, unlike
  91  * writev and pwritev.  The contents of iov after these functions return
  92  * is unspecified.
  93  */
  94 ssize_t writeFull(int fd, const void* buf, size_t n);
  95 ssize_t pwriteFull(int fd, const void* buf, size_t n, off_t offset);
  96 ssize_t writevFull(int fd, iovec* iov, int count);
  97 #ifdef FOLLY_HAVE_PWRITEV
  98 ssize_t pwritevFull(int fd, iovec* iov, int count, off_t offset);
  99 #endif
 100
 101 }  // namespaces
 102
 103 #endif /* FOLLY_FILEUTIL_H_ */
 104