lib/nonblocking.h

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