lib/nonblocking.h

   1 /* Non-blocking I/O for pipe or socket descriptors.
   2    Copyright (C) 2011-2020 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 #ifndef _NONBLOCKING_H
  18 #define _NONBLOCKING_H
  19
  20 #include <stdbool.h>
  21
  22 /* Non-blocking I/O is an I/O mode by which read(), write() calls avoid
  23    blocking the current thread.  When non-blocking is enabled:
  24    - A read() call returns -1 with errno set to EAGAIN when no data or EOF
  25      information is immediately available.
  26    - A write() call returns -1 with errno set to EAGAIN when it cannot
  27      transport the requested amount of data (but at most one pipe buffer)
  28      without blocking.
  29    Non-blocking I/O is most useful for character devices, pipes, and sockets.
  30    Whether it also works on regular files and block devices is platform
  31    dependent.
  32
  33    There are three modern alternatives to non-blocking I/O:
  34      - use select() or poll() followed by read() or write() if the descriptor
  35        is ready,
  36      - call read() or write() in separate threads,
  37      - use <aio.h> interfaces.  */
  38
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44
  45 /* Return 1 if I/O to the descriptor DESC is currently non-blocking, 0
  46    it is blocking, or -1 with errno set if fd is invalid or blocking
  47    status cannot be determined (such as with sockets on mingw).  */
  48 extern int get_nonblocking_flag (int desc);
  49
  50 /* Specify the non-blocking flag for the descriptor DESC.
  51    Return 0 upon success, or -1 with errno set upon failure.
  52    The default depends on the presence of the O_NONBLOCK flag for files
  53    or pipes opened with open() or on the presence of the SOCK_NONBLOCK
  54    flag for sockets.  */
  55 extern int set_nonblocking_flag (int desc, bool value);
  56
  57
  58 #ifdef __cplusplus
  59 }
  60 #endif
  61
  62 #endif /* _NONBLOCKING_H */