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/uio.h>
  23 #include <unistd.h>
  24
  25 namespace folly {
  26
  27 /**
  28  * Convenience wrappers around some commonly used system calls.  The *NoInt
  29  * wrappers retry on EINTR.  The *Full wrappers retry on EINTR and also loop
  30  * until all data is written.  Note that *Full wrappers weaken the thread
  31  * semantics of underlying system calls.
  32  */
  33 int closeNoInt(int fd);
  34 int fsyncNoInt(int fd);
  35 int fdatasyncNoInt(int fd);
  36
  37 ssize_t readNoInt(int fd, void* buf, size_t n);
  38 ssize_t preadNoInt(int fd, void* buf, size_t n, off_t offset);
  39 ssize_t readvNoInt(int fd, const iovec* iov, int count);
  40
  41 ssize_t writeNoInt(int fd, const void* buf, size_t n);
  42 ssize_t pwriteNoInt(int fd, const void* buf, size_t n, off_t offset);
  43 ssize_t writevNoInt(int fd, const iovec* iov, int count);
  44
  45 /**
  46  * Wrapper around read() (and pread()) that, in addition to retrying on
  47  * EINTR, will loop until all data is read.
  48  *
  49  * This wrapper is only useful for blocking file descriptors (for non-blocking
  50  * file descriptors, you have to be prepared to deal with incomplete reads
  51  * anyway), and only exists because POSIX allows read() to return an incomplete
  52  * read if interrupted by a signal (instead of returning -1 and setting errno
  53  * to EINTR).
  54  *
  55  * Note that this wrapper weakens the thread safety of read(): the file pointer
  56  * is shared between threads, but the system call is atomic.  If multiple
  57  * threads are reading from a file at the same time, you don't know where your
  58  * data came from in the file, but you do know that the returned bytes were
  59  * contiguous.  You can no longer make this assumption if using readFull().
  60  * You should probably use pread() when reading from the same file descriptor
  61  * from multiple threads simultaneously, anyway.
  62  *
  63  * Note that readvFull and preadvFull require iov to be non-const, unlike
  64  * readv and preadv.  The contents of iov after these functions return
  65  * is unspecified.
  66  */
  67 ssize_t readFull(int fd, void* buf, size_t n);
  68 ssize_t preadFull(int fd, void* buf, size_t n, off_t offset);
  69 ssize_t readvFull(int fd, iovec* iov, int count);
  70 #ifdef FOLLY_HAVE_PREADV
  71 ssize_t preadvFull(int fd, iovec* iov, int count, off_t offset);
  72 #endif
  73
  74 /**
  75  * Similar to readFull and preadFull above, wrappers around write() and
  76  * pwrite() that loop until all data is written.
  77  *
  78  * Generally, the write() / pwrite() system call may always write fewer bytes
  79  * than requested, just like read().  In certain cases (such as when writing to
  80  * a pipe), POSIX provides stronger guarantees, but not in the general case.
  81  * For example, Linux (even on a 64-bit platform) won't write more than 2GB in
  82  * one write() system call.
  83  *
  84  * Note that writevFull and pwritevFull require iov to be non-const, unlike
  85  * writev and pwritev.  The contents of iov after these functions return
  86  * is unspecified.
  87  */
  88 ssize_t writeFull(int fd, const void* buf, size_t n);
  89 ssize_t pwriteFull(int fd, const void* buf, size_t n, off_t offset);
  90 ssize_t writevFull(int fd, iovec* iov, int count);
  91 #ifdef FOLLY_HAVE_PWRITEV
  92 ssize_t pwritevFull(int fd, iovec* iov, int count, off_t offset);
  93 #endif
  94
  95 }  // namespaces
  96
  97 #endif /* FOLLY_FILEUTIL_H_ */
  98