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