1  /* Non-blocking I/O for pipe or socket descriptors.
       2     Copyright (C) 2011-2023 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 */