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