chiark - git - mdw - mLib/blob - sys/fdflags.3.in

   1 .\" -*-nroff-*-
   2 .\"
   3 .\" Manual for file descriptor flags
   4 .\"
   5 .\" (c) 1999, 2001, 2005, 2009, 2023, 2024 Straylight/Edgeware
   6 .\"
   7 .
   8 .\"----- Licensing notice ---------------------------------------------------
   9 .\"
  10 .\" This file is part of the mLib utilities library.
  11 .\"
  12 .\" mLib is free software: you can redistribute it and/or modify it under
  13 .\" the terms of the GNU Library General Public License as published by
  14 .\" the Free Software Foundation; either version 2 of the License, or (at
  15 .\" your option) any later version.
  16 .\"
  17 .\" mLib is distributed in the hope that it will be useful, but WITHOUT
  18 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  19 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
  20 .\" License for more details.
  21 .\"
  22 .\" You should have received a copy of the GNU Library General Public
  23 .\" License along with mLib.  If not, write to the Free Software
  24 .\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
  25 .\" USA.
  26 .
  27 .\"--------------------------------------------------------------------------
  28 .so ../defs.man \" @@@PRE@@@
  29 .
  30 .\"--------------------------------------------------------------------------
  31 .TH fdflags 3mLib "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
  32 .\" @fdflags
  33 .
  34 .\"--------------------------------------------------------------------------
  35 .SH "NAME"
  36 fdflags \- set file and file descriptor flags
  37 .
  38 .\"--------------------------------------------------------------------------
  39 .SH "SYNOPSIS"
  40 .
  41 .nf
  42 .B "#include <mLib/fdflags.h>"
  43 .PP
  44 .ta \w'\fBint fdflags('u
  45 .BI "int fdflags(int " fd ,
  46 .BI "   unsigned " fbic ", unsigned " fxor ,
  47 .BI "   unsigned " fdbic ", unsigned " fdxor );
  48 .fi
  49 .
  50 .\"--------------------------------------------------------------------------
  51 .SH "DESCRIPTION"
  52 .
  53 .B fdflags
  54 is a convenience function for setting file and file descriptor flags
  55 using
  56 .BR fcntl (2).
  57 .PP
  58 The file flags are read using
  59 .BR F_GETFL ,
  60 the new flags are calculated as
  61 .sp 1
  62 .RS
  63 .I new-flags
  64 =
  65 .BI ( old-flags
  66 .B &
  67 .BI ~ fbic )
  68 .B ^
  69 .I fxor
  70 .RE
  71 .sp 1
  72 and the result written back using
  73 .BR F_SETFL .
  74 .PP
  75 Similarly the file descriptor flags are read using
  76 .BR F_GETFD ,
  77 the new flags calculated as
  78 .sp 1
  79 .RS
  80 .I new-flags
  81 =
  82 .BI ( old-flags
  83 .B &
  84 .BI ~ fdbic )
  85 .B ^
  86 .I fdxor
  87 .RE
  88 .sp 1
  89 and the result written back using
  90 .BR F_SETFD .
  91 .PP
  92 If all went well,
  93 .B fdflags
  94 returns zero; if there was an error, \-1 is returned.
  95 .
  96 .\"--------------------------------------------------------------------------
  97 .SH "EXAMPLES"
  98 .
  99 To set the non-blocking and close-on-exec flags:
 100 .VS
 101 fdflags(fd, O_NONBLOCK, O_NONBLOCK, FD_CLOEXEC, FD_CLOEXEC);
 102 .VE
 103 To clear the non-blocking and close-on-exec flags:
 104 .VS
 105 fdflags(fd, O_NONBLOCK, 0, FD_CLOEXEC, 0);
 106 .VE
 107 .sp -1
 108 .
 109 .\"--------------------------------------------------------------------------
 110 .SH "SEE ALSO"
 111 .
 112 .BR mLib (3).
 113 .
 114 .\"--------------------------------------------------------------------------
 115 .SH "AUTHOR"
 116 .
 117 Mark Wooding, <mdw@distorted.org.uk>
 118 .
 119 .\"----- That's all, folks --------------------------------------------------