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