ghc/docs/users_guide/posix.sgml

   1 <Sect1 id="Posix-library">
   2 <Title>The Posix library
   3 </Title>
   4
   5 <Para>
   6 <IndexTerm><Primary>Posix library</Primary></IndexTerm>
   7 <IndexTerm><Primary>libraries, Posix</Primary></IndexTerm>
   8 </Para>
   9
  10 <Para>
  11 The <Literal>Posix</Literal> interface gives you access to the set of OS
  12 services standardised by POSIX 1003.1b (or the <Emphasis>IEEE Portable
  13 Operating System Interface for Computing Environments</Emphasis> - IEEE Std.
  14 1003.1). The interface is accessed by <Literal>import Posix</Literal> and
  15 adding <Option>-syslib posix</Option> on your command-line.
  16 </Para>
  17
  18 <Sect2 id="Posix-data-types">
  19 <Title>Posix data types
  20 </Title>
  21
  22 <Para>
  23 <IndexTerm><Primary>Posix, data types</Primary></IndexTerm>
  24 </Para>
  25
  26 <Para>
  27
  28 <ProgramListing>
  29 data ByteCount  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  30 </ProgramListing>
  31
  32 </Para>
  33
  34 <Para>
  35 A <Literal>ByteCount</Literal> is a primitive of type <Literal>unsigned</Literal>. At a minimum,
  36 an conforming implementation must support values in the range
  37 <Literal>[0, UINT&lowbar;MAX]</Literal>.
  38 </Para>
  39
  40 <Para>
  41
  42 <ProgramListing>
  43 data ClockTick  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  44 </ProgramListing>
  45
  46 </Para>
  47
  48 <Para>
  49 A <Literal>ClockTick</Literal> is a primitive of type <Literal>clock&lowbar;t</Literal>, which
  50 is used to measure intervals of time in fractions of a second.  The
  51 resolution is determined by <Literal>getSysVar ClockTick</Literal>.
  52 </Para>
  53
  54 <Para>
  55
  56 <ProgramListing>
  57 data DeviceID  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  58 </ProgramListing>
  59
  60 </Para>
  61
  62 <Para>
  63 A <Literal>DeviceID</Literal> is a primitive of type <Literal>dev&lowbar;t</Literal>.  It must
  64 be an arithmetic type.
  65 </Para>
  66
  67 <Para>
  68
  69 <ProgramListing>
  70 data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
  71 </ProgramListing>
  72
  73 </Para>
  74
  75 <Para>
  76 A <Literal>EpochTime</Literal> is a primitive of type <Literal>time&lowbar;t</Literal>, which is
  77 used to measure seconds since the Epoch.  At a minimum, the implementation
  78 must support values in the range <Literal>[0, INT&lowbar;MAX]</Literal>.
  79 </Para>
  80
  81 <Para>
  82
  83 <ProgramListing>
  84 data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
  85 </ProgramListing>
  86
  87 </Para>
  88
  89 <Para>
  90 A <Literal>FileID</Literal> is a primitive of type <Literal>ino&lowbar;t</Literal>.  It must
  91 be an arithmetic type.
  92 </Para>
  93
  94 <Para>
  95
  96 <ProgramListing>
  97 data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
  98 </ProgramListing>
  99
 100 </Para>
 101
 102 <Para>
 103 A <Literal>FileMode</Literal> is a primitive of type <Literal>mode&lowbar;t</Literal>.
 104 It must be an arithmetic type.
 105 </Para>
 106
 107 <Para>
 108
 109 <ProgramListing>
 110 data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
 111 </ProgramListing>
 112
 113 </Para>
 114
 115 <Para>
 116 A <Literal>FileOffset</Literal> is a primitive of type <Literal>off&lowbar;t</Literal>.  It must
 117 be an arithmetic type.
 118 </Para>
 119
 120 <Para>
 121
 122 <ProgramListing>
 123 data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
 124 </ProgramListing>
 125
 126 </Para>
 127
 128 <Para>
 129 A <Literal>GroupID</Literal> is a primitive of type <Literal>gid&lowbar;t</Literal>.  It must
 130 be an arithmetic type.
 131
 132 <ProgramListing>
 133 data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
 134 </ProgramListing>
 135
 136 </Para>
 137
 138 <Para>
 139 A <Literal>Limit</Literal> is a primitive of type <Literal>long</Literal>.
 140 At a minimum, the implementation must support values in the range
 141 <Literal>[LONG&lowbar;MIN, LONG&lowbar;MAX]</Literal>.
 142 </Para>
 143
 144 <Para>
 145
 146 <ProgramListing>
 147 data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
 148 </ProgramListing>
 149
 150 </Para>
 151
 152 <Para>
 153 A <Literal>LinkCount</Literal> is a primitive of type <Literal>nlink&lowbar;t</Literal>.  It must
 154 be an arithmetic type.
 155 </Para>
 156
 157 <Para>
 158
 159 <ProgramListing>
 160 data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
 161 type ProcessGroupID = ProcessID
 162 </ProgramListing>
 163
 164 </Para>
 165
 166 <Para>
 167 A <Literal>ProcessID</Literal> is a primitive of type <Literal>pid&lowbar;t</Literal>.  It
 168 must be a signed arithmetic type.
 169
 170 <ProgramListing>
 171 data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
 172 </ProgramListing>
 173
 174 </Para>
 175
 176 <Para>
 177 A <Literal>UserID</Literal> is a primitive of type <Literal>uid&lowbar;t</Literal>.  It
 178 must be an arithmetic type.
 179 </Para>
 180
 181 <Para>
 182
 183 <ProgramListing>
 184 data DirStream
 185 </ProgramListing>
 186
 187 A <Literal>DirStream</Literal> is a primitive of type <Literal>DIR *</Literal>.
 188 </Para>
 189
 190 <Para>
 191
 192 <ProgramListing>
 193 data FileStatus
 194 </ProgramListing>
 195
 196 A <Literal>FileStatus</Literal> is a primitive of type <Literal>struct stat</Literal>.
 197 </Para>
 198
 199 <Para>
 200
 201 <ProgramListing>
 202 data GroupEntry
 203 </ProgramListing>
 204
 205 </Para>
 206
 207 <Para>
 208 A <Literal>GroupEntry</Literal> is a primitive of type <Literal>struct group</Literal>.
 209
 210 <ProgramListing>
 211 data ProcessTimes
 212 </ProgramListing>
 213
 214 </Para>
 215
 216 <Para>
 217 <Literal>ProcessTimes</Literal> is a primitive structure containing a
 218 <Literal>clock&lowbar;t</Literal> and a <Literal>struct tms</Literal>.
 219 </Para>
 220
 221 <Para>
 222
 223 <ProgramListing>
 224 data SignalSet
 225 </ProgramListing>
 226
 227 </Para>
 228
 229 <Para>
 230 An <Literal>SignalSet</Literal> is a primitive of type <Literal>sigset&lowbar;t</Literal>.
 231 </Para>
 232
 233 <Para>
 234
 235 <ProgramListing>
 236 data SystemID
 237 </ProgramListing>
 238
 239 </Para>
 240
 241 <Para>
 242 A <Literal>SystemID</Literal> is a primitive of type <Literal>struct utsname</Literal>.
 243 </Para>
 244
 245 <Para>
 246
 247 <ProgramListing>
 248 data TerminalAttributes
 249 </ProgramListing>
 250
 251 <Literal>TerminalAttributes</Literal> is a primitive of type <Literal>struct termios</Literal>.
 252 </Para>
 253
 254 <Para>
 255
 256 <ProgramListing>
 257 data UserEntry
 258 </ProgramListing>
 259
 260 </Para>
 261
 262 <Para>
 263 A <Literal>UserEntry</Literal> is a primitive of type <Literal>struct passwd</Literal>.
 264 </Para>
 265
 266 <Para>
 267
 268 <ProgramListing>
 269 data BaudRate = B0 | B50 | B75 | B110 | B134 | B150 | B200 | B300 | B600
 270               | B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
 271               deriving (Eq, Show)
 272
 273 data Fd
 274
 275 intToFd :: Int -&#62; Fd -- use with care.
 276
 277 data FdOption = AppendOnWrite
 278               | CloseOnExec
 279               | NonBlockingRead
 280
 281 data ControlCharacter = EndOfFile
 282                       | EndOfLine
 283                       | Erase
 284                       | Interrupt
 285                       | Kill
 286                       | Quit
 287                       | Suspend
 288                       | Start
 289                       | Stop
 290
 291 type ErrorCode = Int
 292
 293 type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
 294 --                            whence    start       length
 295
 296 data FlowAction = SuspendOutput | RestartOutput | TransmitStop | TransmitStart
 297
 298 data Handler = Default | Ignore | Catch (IO ())
 299
 300 data LockRequest = ReadLock | WriteLock | Unlock
 301                  deriving (Eq, Show)
 302
 303 data OpenMode = ReadOnly | WriteOnly | ReadWrite
 304
 305 data PathVar = LinkLimit
 306              | InputLineLimit
 307              | InputQueueLimit
 308              | FileNameLimit
 309              | PathNameLimit
 310              | PipeBufferLimit
 311              | SetOwnerAndGroupIsRestricted
 312              | FileNamesAreNotTruncated
 313
 314 data QueueSelector = InputQueue | OutputQueue | BothQueues
 315
 316 type Signal = Int
 317
 318 data SysVar = ArgumentLimit
 319             | ChildLimit
 320             | ClockTick
 321             | GroupLimit
 322             | OpenFileLimit
 323             | PosixVersion
 324             | HasSavedIDs
 325             | HasJobControl
 326
 327 data TerminalMode = InterruptOnBreak       -- BRKINT
 328                 | MapCRtoLF                -- ICRNL
 329                 | IgnoreBreak              -- IGNBRK
 330                 | IgnoreCR                 -- IGNCR
 331                 | IgnoreParityErrors       -- IGNPAR
 332                 | MapLFtoCR                -- INLCR
 333                 | CheckParity              -- INPCK
 334                 | StripHighBit             -- ISTRIP
 335                 | StartStopInput           -- IXOFF
 336                 | StartStopOutput          -- IXON
 337                 | MarkParityErrors         -- PARMRK
 338                 | ProcessOutput            -- OPOST
 339                 | LocalMode                -- CLOCAL
 340                 | ReadEnable               -- CREAD
 341                 | TwoStopBits              -- CSTOPB
 342                 | HangupOnClose            -- HUPCL
 343                 | EnableParity             -- PARENB
 344                 | OddParity                -- PARODD
 345                 | EnableEcho               -- ECHO
 346                 | EchoErase                -- ECHOE
 347                 | EchoKill                 -- ECHOK
 348                 | EchoLF                   -- ECHONL
 349                 | ProcessInput             -- ICANON
 350                 | ExtendedFunctions        -- IEXTEN
 351                 | KeyboardInterrupts       -- ISIG
 352                 | NoFlushOnInterrupt       -- NOFLSH
 353                 | BackgroundWriteInterrupt -- TOSTOP
 354
 355 data TerminalState = Immediately | WhenDrained | WhenFlushed
 356
 357 data ProcessStatus = Exited ExitCode
 358                    | Terminated Signal
 359                    | Stopped Signal
 360                    deriving (Eq, Show)
 361 </ProgramListing>
 362
 363 </Para>
 364
 365 </Sect2>
 366
 367 <Sect2 id="Process-Primitives">
 368 <Title>Posix Process Primitives
 369 </Title>
 370
 371 <Para>
 372
 373 <ProgramListing>
 374 forkProcess :: IO (Maybe ProcessID)
 375 </ProgramListing>
 376
 377 </Para>
 378
 379 <Para>
 380 <Function>forkProcess</Function> calls <Function>fork</Function>, returning
 381 <Literal>Just pid</Literal> to the parent, where <VarName>pid</VarName> is the
 382 ProcessID of the child, and returning <Literal>Nothing</Literal> to the
 383 child.
 384 </Para>
 385
 386 <Para>
 387
 388 <ProgramListing>
 389 executeFile :: FilePath                   -- Command
 390             -&#62; Bool                       -- Search PATH?
 391             -&#62; [String]                   -- Arguments
 392             -&#62; Maybe [(String, String)]   -- Environment
 393             -&#62; IO ()
 394 </ProgramListing>
 395
 396 </Para>
 397
 398 <Para>
 399 <Literal>executeFile cmd args env</Literal> calls one of the
 400 <Function>execv*</Function> family, depending on whether or not the current
 401 PATH is to be searched for the command, and whether or not an
 402 environment is provided to supersede the process's current
 403 environment.  The basename (leading directory names suppressed) of
 404 the command is passed to <Function>execv*</Function> as <VarName>arg[0]</VarName>;
 405 the argument list passed to <Function>executeFile</Function> therefore begins with <VarName>arg[1]</VarName>.
 406 </Para>
 407
 408 <Para>
 409
 410 <Screen>
 411 Search PATH?    Supersede environ?      Call
 412 ~~~~~~~~~~~~    ~~~~~~~~~~~~~~~~~~      ~~~~~~~
 413 False           False                   execv
 414 False           True                    execve
 415 True            False                   execvp
 416 True            True                    execvpe*
 417 </Screen>
 418
 419 </Para>
 420
 421 <Para>
 422 Note that <Function>execvpe</Function> is not provided by the POSIX standard, and must
 423 be written by hand.  Care must be taken to ensure that the search path
 424 is extracted from the original environment, and not from the
 425 environment to be passed on to the new image.
 426 </Para>
 427
 428 <Para>
 429 NOTE: In general, sharing open files between parent and child
 430 processes is potential bug farm, and should be avoided unless you
 431 really depend on this `feature' of POSIX' <Function>fork()</Function> semantics. Using
 432 Haskell, there's the extra complication that arguments to
 433 <Function>executeFile</Function> might come from files that are read lazily (using
 434 <Function>hGetContents</Function>, or some such.) If this is the case, then for your own
 435 sanity, please ensure that the arguments to <Function>executeFile</Function> have been
 436 fully evaluated before calling <Function>forkProcess</Function> (followed by
 437 <Function>executeFile</Function>.) Consider yourself warned :-)
 438 </Para>
 439
 440 <Para>
 441 A successful <Function>executeFile</Function> overlays the current process image with
 442 a new one, so it only returns on failure.
 443 </Para>
 444
 445 <Para>
 446
 447 <ProgramListing>
 448 runProcess :: FilePath                    -- Command
 449            -&#62; [String]                    -- Arguments
 450            -&#62; Maybe [(String, String)]    -- Environment (Nothing -&#62; Inherited)
 451            -&#62; Maybe FilePath              -- Working directory (Nothing -&#62; inherited)
 452            -&#62; Maybe Handle                -- stdin  (Nothing -&#62; inherited)
 453            -&#62; Maybe Handle                -- stdout (Nothing -&#62; inherited)
 454            -&#62; Maybe Handle                -- stderr (Nothing -&#62; inherited)
 455            -&#62; IO ()
 456 </ProgramListing>
 457
 458 </Para>
 459
 460 <Para>
 461 <Function>runProcess</Function> is our candidate for the high-level OS-independent
 462 primitive.
 463 </Para>
 464
 465 <Para>
 466 <Literal>runProcess cmd args env wd inhdl outhdl errhdl</Literal> runs <Command>cmd</Command>
 467 (searching the current <Literal>PATH</Literal>) with arguments <Literal>args</Literal>.  If
 468 <Literal>env</Literal> is <Literal>Just pairs</Literal>, the command is executed with the
 469 environment specified by <Literal>pairs</Literal> of variables and values;
 470 otherwise, the command is executed with the current environment.  If
 471 <Literal>wd</Literal> is <Literal>Just dir</Literal>, the command is executed with working
 472 directory <Literal>dir</Literal>; otherwise, the command is executed in the current
 473 working directory.  If <Literal>&lcub;in,out,err</Literal>hdl&rcub; is <Literal>Just handle</Literal>, the
 474 command is executed with the <Literal>Fd</Literal> for <Literal>std&lcub;in,out,err</Literal>&rcub;
 475 attached to the specified <Literal>handle</Literal>; otherwise, the <Literal>Fd</Literal> for
 476 <Literal>std&lcub;in,out,err</Literal>&rcub; is left unchanged.
 477 </Para>
 478
 479 <Para>
 480
 481 <ProgramListing>
 482 getProcessStatus :: Bool              -- Block?
 483                  -&#62; Bool              -- Stopped processes?
 484                  -&#62; ProcessID
 485                  -&#62; IO (Maybe ProcessStatus)
 486 </ProgramListing>
 487
 488 </Para>
 489
 490 <Para>
 491 <Literal>getProcessStatus blk stopped pid</Literal> calls <Function>waitpid</Function>, returning
 492 <Literal>Just tc</Literal>, the <Literal>ProcessStatus</Literal> for process <Literal>pid</Literal> if it is
 493 available, <Literal>Nothing</Literal> otherwise.  If <Literal>blk</Literal> is <Literal>False</Literal>, then
 494 <Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
 495 If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
 496 options for <Function>waitpid</Function>, otherwise not.
 497 </Para>
 498
 499 <Para>
 500
 501 <ProgramListing>
 502 getGroupProcessStatus :: Bool         -- Block?
 503                       -&#62; Bool         -- Stopped processes?
 504                       -&#62; ProcessGroupID
 505                       -&#62; IO (Maybe (ProcessID, ProcessStatus))
 506 </ProgramListing>
 507
 508 </Para>
 509
 510 <Para>
 511 <Literal>getGroupProcessStatus blk stopped pgid</Literal> calls <Function>waitpid</Function>,
 512 returning <Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and
 513 <Literal>ProcessStatus</Literal> for any process in group <Literal>pgid</Literal> if one is
 514 available, <Literal>Nothing</Literal> otherwise.  If <Literal>blk</Literal> is <Literal>False</Literal>, then
 515 <Literal>WNOHANG</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
 516 If <Literal>stopped</Literal> is <Literal>True</Literal>, then <Literal>WUNTRACED</Literal> is set in the
 517 options for <Function>waitpid</Function>, otherwise not.
 518 </Para>
 519
 520 <Para>
 521
 522 <ProgramListing>
 523 getAnyProcessStatus :: Bool           -- Block?
 524                     -&#62; Bool           -- Stopped processes?
 525                     -&#62; IO (Maybe (ProcessID, ProcessStatus))
 526 </ProgramListing>
 527
 528 </Para>
 529
 530 <Para>
 531 <Literal>getAnyProcessStatus blk stopped</Literal> calls <Function>waitpid</Function>, returning
 532 <Literal>Just (pid, tc)</Literal>, the <Literal>ProcessID</Literal> and <Literal>ProcessStatus</Literal> for any
 533 child process if one is available, <Literal>Nothing</Literal> otherwise.  If
 534 <Literal>blk</Literal> is <Literal>False</Literal>, then <Literal>WNOHANG</Literal> is set in the options for
 535 <Function>waitpid</Function>, otherwise not.  If <Literal>stopped</Literal> is <Literal>True</Literal>, then
 536 <Literal>WUNTRACED</Literal> is set in the options for <Function>waitpid</Function>, otherwise not.
 537 </Para>
 538
 539 <Para>
 540
 541 <ProgramListing>
 542 exitImmediately :: ExitCode -&#62; IO ()
 543 </ProgramListing>
 544
 545 </Para>
 546
 547 <Para>
 548 <Literal>exitImmediately status</Literal> calls <Function>&lowbar;exit</Function> to terminate the process
 549 with the indicated exit <Literal>status</Literal>.
 550 The operation never returns.
 551 </Para>
 552
 553 <Para>
 554
 555 <ProgramListing>
 556 getEnvironment :: IO [(String, String)]
 557 </ProgramListing>
 558
 559 </Para>
 560
 561 <Para>
 562 <Function>getEnvironment</Function> parses the environment variable mapping provided by
 563 <Literal>environ</Literal>, returning <Literal>(variable, value)</Literal> pairs.
 564 The operation never fails.
 565 </Para>
 566
 567 <Para>
 568
 569 <ProgramListing>
 570 setEnvironment :: [(String, String)] -&#62; IO ()
 571 </ProgramListing>
 572
 573 </Para>
 574
 575 <Para>
 576 <Function>setEnvironment</Function> replaces the process environment with the provided
 577 mapping of <Literal>(variable, value)</Literal> pairs.
 578 </Para>
 579
 580 <Para>
 581
 582 <ProgramListing>
 583 getEnvVar :: String -&#62; IO String
 584 </ProgramListing>
 585
 586 </Para>
 587
 588 <Para>
 589 <Literal>getEnvVar var</Literal> returns the value associated with variable <VarName>var</VarName>
 590 in the current environment (identical functionality provided through
 591 standard Haskell library function <Function>System.getEnv</Function>).
 592 </Para>
 593
 594 <Para>
 595 The operation may fail with:
 596 </Para>
 597
 598 <Para>
 599 <VariableList>
 600
 601 <VarListEntry>
 602 <Term><Literal>NoSuchThing</Literal></Term>
 603 <ListItem>
 604 <Para>
 605 The variable has no mapping in the current environment.
 606 </Para>
 607 </ListItem>
 608 </VarListEntry>
 609 </VariableList>
 610 </Para>
 611
 612 <Para>
 613
 614 <ProgramListing>
 615 setEnvVar :: String -&#62; String -&#62; IO ()
 616 </ProgramListing>
 617
 618 </Para>
 619
 620 <Para>
 621 <Literal>setEnvVar var val</Literal> sets the value associated with variable <VarName>var</VarName>
 622 in the current environment to be <Literal>val</Literal>.  Any previous mapping is
 623 superseded.
 624 </Para>
 625
 626 <Para>
 627
 628 <ProgramListing>
 629 removeEnvVar :: String -&#62; IO ()
 630 </ProgramListing>
 631
 632 </Para>
 633
 634 <Para>
 635 <Literal>removeEnvVar var</Literal> removes any value associated with variable <VarName>var</VarName>
 636 in the current environment.  Deleting a variable for which there is no mapping
 637 does not generate an error.
 638 </Para>
 639
 640 <Para>
 641
 642 <ProgramListing>
 643 nullSignal :: Signal
 644 nullSignal = 0
 645
 646 backgroundRead, sigTTIN        :: Signal
 647 backgroundWrite, sigTTOU       :: Signal
 648 continueProcess, sigCONT       :: Signal
 649 floatingPointException, sigFPE :: Signal
 650 illegalInstruction, sigILL     :: Signal
 651 internalAbort, sigABRT         :: Signal
 652 keyboardSignal, sigINT         :: Signal
 653 keyboardStop, sigTSTP          :: Signal
 654 keyboardTermination, sigQUIT   :: Signal
 655 killProcess, sigKILL           :: Signal
 656 lostConnection, sigHUP         :: Signal
 657 openEndedPipe, sigPIPE         :: Signal
 658 processStatusChanged, sigCHLD  :: Signal
 659 realTimeAlarm, sigALRM         :: Signal
 660 segmentationViolation, sigSEGV :: Signal
 661 softwareStop, sigSTOP          :: Signal
 662 softwareTermination, sigTERM   :: Signal
 663 userDefinedSignal1, sigUSR1    :: Signal
 664 userDefinedSignal2, sigUSR2    :: Signal
 665
 666 signalProcess :: Signal -&#62; ProcessID -&#62; IO ()
 667 </ProgramListing>
 668
 669 </Para>
 670
 671 <Para>
 672 <Literal>signalProcess int pid</Literal> calls <Function>kill</Function> to signal
 673 process <Literal>pid</Literal> with interrupt signal <Literal>int</Literal>.
 674 </Para>
 675
 676 <Para>
 677
 678 <ProgramListing>
 679 raiseSignal :: Signal -&#62; IO ()
 680 </ProgramListing>
 681
 682 </Para>
 683
 684 <Para>
 685 <Literal>raiseSignal int</Literal> calls <Function>kill</Function> to signal the current process
 686 with interrupt signal <Literal>int</Literal>.
 687 </Para>
 688
 689 <Para>
 690
 691 <ProgramListing>
 692 signalProcessGroup :: Signal -&#62; ProcessGroupID -&#62; IO ()
 693 </ProgramListing>
 694
 695 </Para>
 696
 697 <Para>
 698 <Literal>signalProcessGroup int pgid</Literal> calls <Function>kill</Function> to signal
 699 all processes in group <Literal>pgid</Literal> with interrupt signal <Literal>int</Literal>.
 700 </Para>
 701
 702 <Para>
 703
 704 <ProgramListing>
 705 setStoppedChildFlag :: Bool -&#62; IO Bool
 706 </ProgramListing>
 707
 708 </Para>
 709
 710 <Para>
 711 <Literal>setStoppedChildFlag bool</Literal> sets a flag which controls whether or
 712 not the <Constant>NOCLDSTOP</Constant> option will be used the next time a signal
 713 handler is installed for <Constant>SIGCHLD</Constant>.  If <Literal>bool</Literal> is <Literal>True</Literal> (the
 714 default), <Constant>NOCLDSTOP</Constant> will not be used; otherwise it will be.  The
 715 operation never fails.
 716 </Para>
 717
 718 <Para>
 719
 720 <ProgramListing>
 721 queryStoppedChildFlag :: IO Bool
 722 </ProgramListing>
 723
 724 </Para>
 725
 726 <Para>
 727 <Function>queryStoppedChildFlag</Function> queries the flag which
 728 controls whether or not the <Constant>NOCLDSTOP</Constant> option will be used
 729 the next time a signal handler is installed for <Constant>SIGCHLD</Constant>.
 730 If <Constant>NOCLDSTOP</Constant> will be used, it returns <Literal>False</Literal>;
 731 otherwise (the default) it returns <Literal>True</Literal>.
 732 The operation never fails.
 733 </Para>
 734
 735 <Para>
 736
 737 <ProgramListing>
 738 emptySignalSet :: SignalSet
 739 fullSignalSet  :: SignalSet
 740 addSignal      :: Signal -&#62; SignalSet -&#62; SignalSet
 741 deleteSignal   :: Signal -&#62; SignalSet -&#62; SignalSet
 742 inSignalSet    :: Signal -&#62; SignalSet -&#62; Bool
 743
 744 installHandler :: Signal
 745                -&#62; Handler
 746                -&#62; Maybe SignalSet       -- other signals to block
 747                -&#62; IO Handler            -- old handler
 748 </ProgramListing>
 749
 750 </Para>
 751
 752 <Para>
 753 <Literal>installHandler int handler iset</Literal> calls <Constant>sigaction</Constant> to install an
 754 interrupt handler for signal <Literal>int</Literal>.  If <Literal>handler</Literal> is <Literal>Default</Literal>,
 755 <Constant>SIG&lowbar;DFL</Constant> is installed; if <Literal>handler</Literal> is <Literal>Ignore</Literal>, <Constant>SIG&lowbar;IGN</Constant> is
 756 installed; if <Literal>handler</Literal> is <Literal>Catch action</Literal>, a handler is installed
 757 which will invoke <Literal>action</Literal> in a new thread when (or shortly after) the
 758 signal is received.  See <XRef LinkEnd="concurrent-haskell"> for details on how to communicate between
 759 threads.
 760 </Para>
 761
 762 <Para>
 763 If <Literal>iset</Literal> is <Literal>Just s</Literal>, then the <VarName>sa&lowbar;mask</VarName> of the <Literal>sigaction</Literal> structure
 764 is set to <Literal>s</Literal>; otherwise it is cleared.  The previously installed
 765 signal handler for <Literal>int</Literal> is returned.
 766 </Para>
 767
 768 <Para>
 769
 770 <ProgramListing>
 771 getSignalMask :: IO SignalSet
 772 </ProgramListing>
 773
 774 </Para>
 775
 776 <Para>
 777 <Function>getSignalMask</Function> calls <Function>sigprocmask</Function> to determine the
 778 set of interrupts which are currently being blocked.
 779 </Para>
 780
 781 <Para>
 782
 783 <ProgramListing>
 784 setSignalMask :: SignalSet -&#62; IO SignalSet
 785 </ProgramListing>
 786
 787 </Para>
 788
 789 <Para>
 790 <Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
 791 <Constant>SIG&lowbar;SETMASK</Constant> to block all interrupts in <Literal>mask</Literal>.  The
 792 previous set of blocked interrupts is returned.
 793 </Para>
 794
 795 <Para>
 796
 797 <ProgramListing>
 798 blockSignals :: SignalSet -&#62; IO SignalSet
 799 </ProgramListing>
 800
 801 </Para>
 802
 803 <Para>
 804 <Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
 805 <Constant>SIG&lowbar;BLOCK</Constant> to add all interrupts in <Literal>mask</Literal> to the
 806 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 807 </Para>
 808
 809 <Para>
 810
 811 <ProgramListing>
 812 unBlockSignals :: SignalSet -&#62; IO SignalSet
 813 </ProgramListing>
 814
 815 </Para>
 816
 817 <Para>
 818 <Literal>setSignalMask mask</Literal> calls <Function>sigprocmask</Function> with
 819 <Constant>SIG&lowbar;UNBLOCK</Constant> to remove all interrupts in <Literal>mask</Literal> from the
 820 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 821 </Para>
 822
 823 <Para>
 824
 825 <ProgramListing>
 826 getPendingSignals :: IO SignalSet
 827 </ProgramListing>
 828
 829 </Para>
 830
 831 <Para>
 832 <Function>getPendingSignals</Function> calls <Function>sigpending</Function> to obtain
 833 the set of interrupts which have been received but are currently blocked.
 834 </Para>
 835
 836 <Para>
 837
 838 <ProgramListing>
 839 awaitSignal :: Maybe SignalSet -&#62; IO ()
 840 </ProgramListing>
 841
 842 </Para>
 843
 844 <Para>
 845 <Literal>awaitSignal iset</Literal> suspends execution until an interrupt is received.
 846 If <Literal>iset</Literal> is <Literal>Just s</Literal>, <Function>awaitSignal</Function> calls <Function>sigsuspend</Function>, installing
 847 <Literal>s</Literal> as the new signal mask before suspending execution; otherwise, it
 848 calls <Function>pause</Function>.  <Function>awaitSignal</Function> returns on receipt of a signal.  If you
 849 have installed any signal handlers with <Function>installHandler</Function>, it may be
 850 wise to call <Function>yield</Function> directly after <Function>awaitSignal</Function> to ensure that the
 851 signal handler runs as promptly.
 852 </Para>
 853
 854 <Para>
 855
 856 <ProgramListing>
 857 scheduleAlarm :: Int -&#62; IO Int
 858 </ProgramListing>
 859
 860 </Para>
 861
 862 <Para>
 863 <Literal>scheduleAlarm i</Literal> calls <Function>alarm</Function> to schedule a real time
 864 alarm at least <Literal>i</Literal> seconds in the future.
 865 </Para>
 866
 867 <Para>
 868
 869 <ProgramListing>
 870 sleep :: Int -&#62; IO ()
 871 </ProgramListing>
 872
 873 </Para>
 874
 875 <Para>
 876 <Literal>sleep i</Literal> calls <Function>sleep</Function> to suspend execution of the
 877 program until at least <Literal>i</Literal> seconds have elapsed or a signal is
 878 received.
 879 </Para>
 880
 881 </Sect2>
 882
 883 <Sect2 id="Process-Environment">
 884 <Title>Posix Process Environment
 885 </Title>
 886
 887 <Para>
 888 <IndexTerm><Primary>Posix, process environment</Primary></IndexTerm>
 889 </Para>
 890
 891 <Para>
 892
 893 <ProgramListing>
 894 getProcessID :: IO ProcessID
 895 </ProgramListing>
 896
 897 </Para>
 898
 899 <Para>
 900 <Function>getProcessID</Function> calls <Function>getpid</Function> to obtain the <Literal>ProcessID</Literal> for
 901 the current process.
 902 </Para>
 903
 904 <Para>
 905
 906 <ProgramListing>
 907 getParentProcessID :: IO ProcessID
 908 </ProgramListing>
 909
 910 </Para>
 911
 912 <Para>
 913 <Function>getProcessID</Function> calls <Function>getppid</Function> to obtain the <Literal>ProcessID</Literal> for
 914 the parent of the current process.
 915 </Para>
 916
 917 <Para>
 918
 919 <ProgramListing>
 920 getRealUserID :: IO UserID
 921 </ProgramListing>
 922
 923 </Para>
 924
 925 <Para>
 926 <Function>getRealUserID</Function> calls <Function>getuid</Function> to obtain the real <Literal>UserID</Literal>
 927 associated with the current process.
 928 </Para>
 929
 930 <Para>
 931
 932 <ProgramListing>
 933 getEffectiveUserID :: IO UserID
 934 </ProgramListing>
 935
 936 </Para>
 937
 938 <Para>
 939 <Function>getRealUserID</Function> calls <Function>geteuid</Function> to obtain the effective
 940 <Literal>UserID</Literal> associated with the current process.
 941 </Para>
 942
 943 <Para>
 944
 945 <ProgramListing>
 946 setUserID :: UserID -&#62; IO ()
 947 </ProgramListing>
 948
 949 </Para>
 950
 951 <Para>
 952 <Literal>setUserID uid</Literal> calls <Function>setuid</Function> to set the real, effective, and
 953 saved set-user-id associated with the current process to <Literal>uid</Literal>.
 954 </Para>
 955
 956 <Para>
 957
 958 <ProgramListing>
 959 getLoginName :: IO String
 960 </ProgramListing>
 961
 962 </Para>
 963
 964 <Para>
 965 <Function>getLoginName</Function> calls <Function>getlogin</Function> to obtain the login name
 966 associated with the current process.
 967 </Para>
 968
 969 <Para>
 970
 971 <ProgramListing>
 972 getRealGroupID :: IO GroupID
 973 </ProgramListing>
 974
 975 </Para>
 976
 977 <Para>
 978 <Function>getRealGroupID</Function> calls <Function>getgid</Function> to obtain the real <Literal>GroupID</Literal>
 979 associated with the current process.
 980 </Para>
 981
 982 <Para>
 983
 984 <ProgramListing>
 985 getEffectiveGroupID :: IO GroupID
 986 </ProgramListing>
 987
 988 </Para>
 989
 990 <Para>
 991 <Function>getEffectiveGroupID</Function> calls <Function>getegid</Function> to obtain the effective
 992 <Literal>GroupID</Literal> associated with the current process.
 993 </Para>
 994
 995 <Para>
 996
 997 <ProgramListing>
 998 setGroupID :: GroupID -&#62; IO ()
 999 </ProgramListing>
1000
1001 </Para>
1002
1003 <Para>
1004 <Literal>setGroupID gid</Literal> calls <Function>setgid</Function> to set the real, effective, and
1005 saved set-group-id associated with the current process to <Literal>gid</Literal>.
1006 </Para>
1007
1008 <Para>
1009
1010 <ProgramListing>
1011 getGroups :: IO [GroupID]
1012 </ProgramListing>
1013
1014 </Para>
1015
1016 <Para>
1017 <Function>getGroups</Function> calls <Function>getgroups</Function> to obtain the list of
1018 supplementary <Literal>GroupID</Literal>s associated with the current process.
1019 </Para>
1020
1021 <Para>
1022
1023 <ProgramListing>
1024 getEffectiveUserName :: IO String
1025 </ProgramListing>
1026
1027 </Para>
1028
1029 <Para>
1030 <Function>getEffectiveUserName</Function> calls <Function>cuserid</Function> to obtain a name
1031 associated with the effective <Literal>UserID</Literal> of the process.
1032 </Para>
1033
1034 <Para>
1035
1036 <ProgramListing>
1037 getProcessGroupID :: IO ProcessGroupID
1038 </ProgramListing>
1039
1040 </Para>
1041
1042 <Para>
1043 <Function>getProcessGroupID</Function> calls <Function>getpgrp</Function> to obtain the
1044 <Literal>ProcessGroupID</Literal> for the current process.
1045 </Para>
1046
1047 <Para>
1048
1049 <ProgramListing>
1050 createProcessGroup :: ProcessID -&#62; IO ProcessGroupID
1051 </ProgramListing>
1052
1053 </Para>
1054
1055 <Para>
1056 <Literal>createProcessGroup pid</Literal> calls <Function>setpgid</Function> to make
1057 process <Literal>pid</Literal> a new process group leader.
1058 </Para>
1059
1060 <Para>
1061
1062 <ProgramListing>
1063 joinProcessGroup :: ProcessGroupID -&#62; IO ProcessGroupID
1064 </ProgramListing>
1065
1066 </Para>
1067
1068 <Para>
1069 <Literal>joinProcessGroup pgid</Literal> calls <Function>setpgid</Function> to set the
1070 <Literal>ProcessGroupID</Literal> of the current process to <Literal>pgid</Literal>.
1071 </Para>
1072
1073 <Para>
1074
1075 <ProgramListing>
1076 setProcessGroupID :: ProcessID -&#62; ProcessGroupID -&#62; IO ()
1077 </ProgramListing>
1078
1079 </Para>
1080
1081 <Para>
1082 <Literal>setProcessGroupID pid pgid</Literal> calls <Function>setpgid</Function> to set the
1083 <Literal>ProcessGroupID</Literal> for process <Literal>pid</Literal> to <Literal>pgid</Literal>.
1084 </Para>
1085
1086 <Para>
1087
1088 <ProgramListing>
1089 createSession :: IO ProcessGroupID
1090 </ProgramListing>
1091
1092 </Para>
1093
1094 <Para>
1095 <Function>createSession</Function> calls <Function>setsid</Function> to create a new session
1096 with the current process as session leader.
1097 </Para>
1098
1099 <Para>
1100
1101 <ProgramListing>
1102 systemName :: SystemID -&#62; String
1103 nodeName :: SystemID -&#62; String
1104 release :: SystemID -&#62; String
1105 version :: SystemID -&#62; String
1106 machine :: SystemID -&#62; String
1107
1108 getSystemID :: IO SystemID
1109 </ProgramListing>
1110
1111 </Para>
1112
1113 <Para>
1114 <Function>getSystemID</Function> calls <Function>uname</Function> to obtain information
1115 about the current operating system.
1116 </Para>
1117
1118 <Para>
1119
1120 <ProgramListing>
1121 &#62; epochTime :: IO EpochTime
1122 </ProgramListing>
1123
1124 </Para>
1125
1126 <Para>
1127 <Function>epochTime</Function> calls <Function>time</Function> to obtain the number of
1128 seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
1129 </Para>
1130
1131 <Para>
1132
1133 <ProgramListing>
1134 elapsedTime     :: ProcessTimes -&#62; ClockTick
1135 userTime        :: ProcessTimes -&#62; ClockTick
1136 systemTime      :: ProcessTimes -&#62; ClockTick
1137 childUserTime   :: ProcessTimes -&#62; ClockTick
1138 childSystemTime :: ProcessTimes -&#62; ClockTick
1139
1140 getProcessTimes :: IO ProcessTimes
1141 </ProgramListing>
1142
1143 </Para>
1144
1145 <Para>
1146 <Function>getProcessTimes</Function> calls <Function>times</Function> to obtain time-accounting
1147 information for the current process and its children.
1148 </Para>
1149
1150 <Para>
1151
1152 <ProgramListing>
1153 getControllingTerminalName :: IO FilePath
1154 </ProgramListing>
1155
1156 </Para>
1157
1158 <Para>
1159 <Function>getControllingTerminalName</Function> calls <Function>ctermid</Function> to obtain
1160 a name associated with the controlling terminal for the process.  If a
1161 controlling terminal exists,
1162 <Function>getControllingTerminalName</Function> returns the name of the
1163 controlling terminal.
1164 </Para>
1165
1166 <Para>
1167 The operation may fail with:
1168 </Para>
1169
1170 <Para>
1171 <VariableList>
1172
1173 <VarListEntry>
1174 <Term><Literal>NoSuchThing</Literal></Term>
1175 <ListItem>
1176 <Para>
1177 There is no controlling terminal, or its name cannot be determined.
1178 </Para>
1179 </ListItem>
1180 </VarListEntry>
1181 <VarListEntry>
1182 <Term><Literal>SystemError</Literal></Term>
1183 <ListItem>
1184 <Para>
1185 Various other causes.
1186 </Para>
1187 </ListItem>
1188 </VarListEntry>
1189 </VariableList>
1190 </Para>
1191
1192 <Para>
1193
1194 <ProgramListing>
1195 getTerminalName :: Fd -&#62; IO FilePath
1196 </ProgramListing>
1197
1198 </Para>
1199
1200 <Para>
1201 <Literal>getTerminalName fd</Literal> calls <Function>ttyname</Function> to obtain a name associated
1202 with the terminal for <Literal>Fd</Literal> <Literal>fd</Literal>. If <Literal>fd</Literal> is associated
1203 with a terminal, <Function>getTerminalName</Function> returns the name of the
1204 terminal.
1205 </Para>
1206
1207 <Para>
1208 The operation may fail with:
1209 </Para>
1210
1211 <Para>
1212 <VariableList>
1213
1214 <VarListEntry>
1215 <Term><Literal>InappropriateType</Literal></Term>
1216 <ListItem>
1217 <Para>
1218 The channel is not associated with a terminal.
1219 </Para>
1220 </ListItem>
1221 </VarListEntry>
1222 <VarListEntry>
1223 <Term><Literal>NoSuchThing</Literal></Term>
1224 <ListItem>
1225 <Para>
1226 The channel is associated with a terminal, but it has no name.
1227 </Para>
1228 </ListItem>
1229 </VarListEntry>
1230 <VarListEntry>
1231 <Term><Literal>SystemError</Literal></Term>
1232 <ListItem>
1233 <Para>
1234 Various other causes.
1235 </Para>
1236 </ListItem>
1237 </VarListEntry>
1238 </VariableList>
1239 </Para>
1240
1241 <Para>
1242
1243 <ProgramListing>
1244 queryTerminal :: Fd -&#62; IO Bool
1245 </ProgramListing>
1246
1247 </Para>
1248
1249 <Para>
1250 <Literal>queryTerminal fd</Literal> calls <Function>isatty</Function> to determine whether or
1251 not <Literal>Fd</Literal> <Literal>fd</Literal> is associated with a terminal.
1252 </Para>
1253
1254 <Para>
1255
1256 <ProgramListing>
1257 getSysVar :: SysVar -&#62; IO Limit
1258 </ProgramListing>
1259
1260 </Para>
1261
1262 <Para>
1263 <Literal>getSysVar var</Literal> calls <Function>sysconf</Function> to obtain the
1264 dynamic value of the requested configurable system limit or option.
1265 For defined system limits, <Function>getSysVar</Function> returns the associated
1266 value.  For defined system options, the result of <Function>getSysVar</Function>
1267 is undefined, but not failure.
1268 </Para>
1269
1270 <Para>
1271 The operation may fail with:
1272 </Para>
1273
1274 <Para>
1275 <VariableList>
1276
1277 <VarListEntry>
1278 <Term><Literal>NoSuchThing</Literal></Term>
1279 <ListItem>
1280 <Para>
1281 The requested system limit or option is undefined.
1282 </Para>
1283 </ListItem>
1284 </VarListEntry>
1285 </VariableList>
1286 </Para>
1287
1288 </Sect2>
1289
1290 <Sect2 id="Files-and-Directories">
1291 <Title>Posix operations on files and directories
1292 </Title>
1293
1294 <Para>
1295 <IndexTerm><Primary>Posix, files and directories</Primary></IndexTerm>
1296 </Para>
1297
1298 <Para>
1299
1300 <ProgramListing>
1301 openDirStream :: FilePath -&#62; IO DirStream
1302 </ProgramListing>
1303
1304 </Para>
1305
1306 <Para>
1307 <Literal>openDirStream dir</Literal> calls <Function>opendir</Function> to obtain a
1308 directory stream for <Literal>dir</Literal>.
1309 </Para>
1310
1311 <Para>
1312
1313 <ProgramListing>
1314 readDirStream :: DirStream -&#62; IO String
1315 </ProgramListing>
1316
1317 </Para>
1318
1319 <Para>
1320 <Literal>readDirStream dp</Literal> calls <Function>readdir</Function> to obtain the
1321 next directory entry (<Literal>struct dirent</Literal>) for the open directory
1322 stream <Literal>dp</Literal>, and returns the <VarName>d&lowbar;name</VarName> member of that
1323 structure.
1324 </Para>
1325
1326 <Para>
1327 The operation may fail with:
1328 </Para>
1329
1330 <Para>
1331 <VariableList>
1332
1333 <VarListEntry>
1334 <Term><Literal>EOF</Literal></Term>
1335 <ListItem>
1336 <Para>
1337 End of file has been reached.
1338 </Para>
1339 </ListItem>
1340 </VarListEntry>
1341 <VarListEntry>
1342 <Term><Literal>SystemError</Literal></Term>
1343 <ListItem>
1344 <Para>
1345 Various other causes.
1346 </Para>
1347 </ListItem>
1348 </VarListEntry>
1349 </VariableList>
1350 </Para>
1351
1352 <Para>
1353
1354 <ProgramListing>
1355 rewindDirStream :: DirStream -&#62; IO ()
1356 </ProgramListing>
1357
1358 </Para>
1359
1360 <Para>
1361 <Literal>rewindDirStream dp</Literal> calls <Function>rewinddir</Function> to reposition
1362 the directory stream <Literal>dp</Literal> at the beginning of the directory.
1363 </Para>
1364
1365 <Para>
1366
1367 <ProgramListing>
1368 closeDirStream :: DirStream -&#62; IO ()
1369 </ProgramListing>
1370
1371 </Para>
1372
1373 <Para>
1374 <Literal>closeDirStream dp</Literal> calls <Function>closedir</Function> to close
1375 the directory stream <Literal>dp</Literal>.
1376 </Para>
1377
1378 <Para>
1379
1380 <ProgramListing>
1381 getWorkingDirectory :: IO FilePath
1382 </ProgramListing>
1383
1384 </Para>
1385
1386 <Para>
1387 <Function>getWorkingDirectory</Function> calls <Function>getcwd</Function> to obtain the name
1388 of the current working directory.
1389 </Para>
1390
1391 <Para>
1392
1393 <ProgramListing>
1394 changeWorkingDirectory :: FilePath -&#62; IO ()
1395 </ProgramListing>
1396
1397 </Para>
1398
1399 <Para>
1400 <Literal>changeWorkingDirectory dir</Literal> calls <Function>chdir</Function> to change
1401 the current working directory to <Literal>dir</Literal>.
1402 </Para>
1403
1404 <Para>
1405 <ProgramListing>
1406 nullFileMode       :: FileMode       -- ---------
1407 ownerReadMode      :: FileMode       -- r--------
1408 ownerWriteMode     :: FileMode       -- -w-------
1409 ownerExecuteMode   :: FileMode       -- --x------
1410 groupReadMode      :: FileMode       -- ---r-----
1411 groupWriteMode     :: FileMode       -- ----w----
1412 groupExecuteMode   :: FileMode       -- -----x---
1413 otherReadMode      :: FileMode       -- ------r--
1414 otherWriteMode     :: FileMode       -- -------w-
1415 otherExecuteMode   :: FileMode       -- --------x
1416 setUserIDMode      :: FileMode       -- --S------
1417 setGroupIDMode     :: FileMode       -- -----S---
1418
1419 stdFileMode        :: FileMode       -- rw-rw-rw-
1420
1421 ownerModes         :: FileMode       -- rwx------
1422 groupModes         :: FileMode       -- ---rwx---
1423 otherModes         :: FileMode       -- ------rwx
1424 accessModes        :: FileMode       -- rwxrwxrwx
1425
1426 unionFileModes     :: FileMode -&#62; FileMode -&#62; FileMode
1427 intersectFileModes :: FileMode -&#62; FileMode -&#62; FileMode
1428
1429 stdInput  :: Fd
1430 stdInput  = intToFd 0
1431
1432 stdOutput :: Fd
1433 stdOutput = intToFd 1
1434
1435 stdError  :: Fd
1436 stdError  = intToFd 2
1437
1438 data OpenFileFlags =
1439  OpenFileFlags {
1440     append    :: Bool,
1441     exclusive :: Bool,
1442     noctty    :: Bool,
1443     nonBlock  :: Bool,
1444     trunc     :: Bool
1445  }
1446
1447 openFd :: FilePath
1448        -&#62; OpenMode
1449        -&#62; Maybe FileMode  -- Just x =&#62; O_CREAT, Nothing =&#62; must exist
1450        -&#62; OpenFileFlags
1451        -&#62; IO Fd
1452 </ProgramListing>
1453 </Para>
1454
1455 <Para>
1456 <Literal>openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)</Literal> calls
1457 <Function>open</Function> to obtain a <Literal>Fd</Literal> for the file <Literal>path</Literal> with access
1458 mode <Literal>acc</Literal>.  If <Literal>mode</Literal> is <Literal>Just m</Literal>, the <Constant>O&lowbar;CREAT</Constant> flag is
1459 set and the file's permissions will be based on <Literal>m</Literal> if it does not
1460 already exist; otherwise, the <Constant>O&lowbar;CREAT</Constant> flag is not set.  The
1461 arguments <Literal>app</Literal>, <Literal>excl</Literal>, <Literal>noctty</Literal>, <Literal>nonblock</Literal>, and
1462 <Literal>trunc</Literal> control whether or not the flags <Constant>O&lowbar;APPEND</Constant>,
1463 <Constant>O&lowbar;EXCL</Constant>, <Constant>O&lowbar;NOCTTY</Constant>, <Constant>O&lowbar;NONBLOCK</Constant>, and <Constant>O&lowbar;TRUNC</Constant> are set,
1464 respectively.
1465 </Para>
1466
1467 <Para>
1468
1469 <ProgramListing>
1470 createFile :: FilePath -&#62; FileMode -&#62; IO Fd
1471 </ProgramListing>
1472
1473 </Para>
1474
1475 <Para>
1476 <Literal>createFile path mode</Literal> calls <Function>creat</Function> to obtain a <Literal>Fd</Literal>
1477 for file <Literal>path</Literal>, which will be created with permissions based on
1478 <Literal>mode</Literal> if it does not already exist.
1479 </Para>
1480
1481 <Para>
1482
1483 <ProgramListing>
1484 setFileCreationMask :: FileMode -&#62; IO FileMode
1485 </ProgramListing>
1486
1487 </Para>
1488
1489 <Para>
1490 <Literal>setFileCreationMask mode</Literal> calls <Function>umask</Function> to set
1491 the process's file creation mask to <Literal>mode</Literal>.  The previous file
1492 creation mask is returned.
1493 </Para>
1494
1495 <Para>
1496
1497 <ProgramListing>
1498 createLink :: FilePath -&#62; FilePath -&#62; IO ()
1499 </ProgramListing>
1500
1501 </Para>
1502
1503 <Para>
1504 <Literal>createLink old new</Literal> calls <Function>link</Function> to create a
1505 new path, <Literal>new</Literal>, linked to an existing file, <Literal>old</Literal>.
1506
1507 <ProgramListing>
1508 createDirectory :: FilePath -&#62; FileMode -&#62; IO ()
1509 </ProgramListing>
1510
1511 </Para>
1512
1513 <Para>
1514 <Literal>createDirectory dir mode</Literal> calls <Function>mkdir</Function> to
1515 create a new directory, <Literal>dir</Literal>, with permissions based on
1516 <Literal>mode</Literal>.
1517 </Para>
1518
1519 <Para>
1520
1521 <ProgramListing>
1522 createNamedPipe :: FilePath -&#62; FileMode -&#62; IO ()
1523 </ProgramListing>
1524
1525 </Para>
1526
1527 <Para>
1528 <Literal>createNamedPipe fifo mode</Literal> calls <Function>mkfifo</Function> to
1529 create a new named pipe, <Literal>fifo</Literal>, with permissions based on
1530 <Literal>mode</Literal>.
1531 </Para>
1532
1533 <Para>
1534
1535 <ProgramListing>
1536 removeLink :: FilePath -&#62; IO ()
1537 </ProgramListing>
1538
1539 </Para>
1540
1541 <Para>
1542 <Literal>removeLink path</Literal> calls <Function>unlink</Function> to remove the link
1543 named <Literal>path</Literal>.
1544 </Para>
1545
1546 <Para>
1547
1548 <ProgramListing>
1549 removeDirectory :: FilePath -&#62; IO ()
1550 </ProgramListing>
1551
1552 </Para>
1553
1554 <Para>
1555 <Literal>removeDirectory dir</Literal> calls <Function>rmdir</Function> to remove the
1556 directory named <Literal>dir</Literal>.
1557 </Para>
1558
1559 <Para>
1560
1561 <ProgramListing>
1562 rename :: FilePath -&#62; FilePath -&#62; IO ()
1563 </ProgramListing>
1564
1565 </Para>
1566
1567 <Para>
1568 <Literal>rename old new</Literal> calls <Function>rename</Function> to rename a
1569 file or directory from <Literal>old</Literal> to <Literal>new</Literal>.
1570 </Para>
1571
1572 <Para>
1573
1574 <ProgramListing>
1575 fileMode          :: FileStatus -&#62; FileMode
1576
1577 fileID            :: FileStatus -&#62; FileID
1578 deviceID          :: FileStatus -&#62; DeviceID
1579
1580 linkCount         :: FileStatus -&#62; LinkCount
1581
1582 fileOwner         :: FileStatus -&#62; UserID
1583 fileGroup         :: FileStatus -&#62; GroupID
1584 fileSize          :: FileStatus -&#62; FileOffset
1585
1586 accessTime        :: FileStatus -&#62; EpochTime
1587 modificationTime  :: FileStatus -&#62; EpochTime
1588 statusChangeTime  :: FileStatus -&#62; EpochTime
1589
1590 isDirectory       :: FileStatus -&#62; Bool
1591 isCharacterDevice :: FileStatus -&#62; Bool
1592 isBlockDevice     :: FileStatus -&#62; Bool
1593 isRegularFile     :: FileStatus -&#62; Bool
1594 isNamedPipe       :: FileStatus -&#62; Bool
1595
1596 getFileStatus     :: FilePath -&#62; IO FileStatus
1597 </ProgramListing>
1598
1599 </Para>
1600
1601 <Para>
1602 <Literal>getFileStatus path</Literal> calls <Function>stat</Function> to get the
1603 <Literal>FileStatus</Literal> information for the file <Literal>path</Literal>.
1604 </Para>
1605
1606 <Para>
1607
1608 <ProgramListing>
1609 getFdStatus :: Fd -&#62; IO FileStatus
1610 </ProgramListing>
1611
1612 </Para>
1613
1614 <Para>
1615 <Literal>getFdStatus fd</Literal> calls <Function>fstat</Function> to get the
1616 <Literal>FileStatus</Literal> information for the file associated with
1617 <Literal>Fd</Literal> <Literal>fd</Literal>.
1618 </Para>
1619
1620 <Para>
1621
1622 <ProgramListing>
1623 queryAccess :: FilePath -&#62; Bool -&#62; Bool -&#62; Bool -&#62; IO Bool
1624 </ProgramListing>
1625
1626 </Para>
1627
1628 <Para>
1629 <Literal>queryAccess path r w x</Literal> calls <Function>access</Function> to test the access
1630 permissions for file <Literal>path</Literal>.  The three arguments, <Literal>r</Literal>, <Literal>w</Literal>,
1631 and <Literal>x</Literal> control whether or not <Function>access</Function> is called with
1632 <Constant>R&lowbar;OK</Constant>, <Constant>W&lowbar;OK</Constant>, and <Constant>X&lowbar;OK</Constant> respectively.
1633 </Para>
1634
1635 <Para>
1636
1637 <ProgramListing>
1638 queryFile :: FilePath -&#62; IO Bool
1639 </ProgramListing>
1640
1641 </Para>
1642
1643 <Para>
1644 <Literal>queryFile path</Literal> calls <Function>access</Function> with <Constant>F&lowbar;OK</Constant> to test for the
1645 existence for file <Literal>path</Literal>.
1646 </Para>
1647
1648 <Para>
1649
1650 <ProgramListing>
1651 setFileMode :: FilePath -&#62; FileMode -&#62; IO ()
1652 </ProgramListing>
1653
1654 </Para>
1655
1656 <Para>
1657 <Literal>setFileMode path mode</Literal> calls <Function>chmod</Function> to set the
1658 permission bits associated with file <Literal>path</Literal> to <Literal>mode</Literal>.
1659 </Para>
1660
1661 <Para>
1662
1663 <ProgramListing>
1664 setOwnerAndGroup :: FilePath -&#62; UserID -&#62; GroupID -&#62; IO ()
1665 </ProgramListing>
1666
1667 </Para>
1668
1669 <Para>
1670 <Literal>setOwnerAndGroup path uid gid</Literal> calls <Function>chown</Function> to
1671 set the <Literal>UserID</Literal> and <Literal>GroupID</Literal> associated with file
1672 <Literal>path</Literal> to <Literal>uid</Literal> and <Literal>gid</Literal>, respectively.
1673 </Para>
1674
1675 <Para>
1676
1677 <ProgramListing>
1678 setFileTimes :: FilePath -&#62; EpochTime -&#62; EpochTime -&#62; IO ()
1679 </ProgramListing>
1680
1681 </Para>
1682
1683 <Para>
1684 <Literal>setFileTimes path atime mtime</Literal> calls <Function>utime</Function> to
1685 set the access and modification times associated with file
1686 <Literal>path</Literal> to <Literal>atime</Literal> and <Literal>mtime</Literal>, respectively.
1687 </Para>
1688
1689 <Para>
1690
1691 <ProgramListing>
1692 touchFile :: FilePath -&#62; IO ()
1693 </ProgramListing>
1694
1695 </Para>
1696
1697 <Para>
1698 <Literal>touchFile path</Literal> calls <Function>utime</Function> to
1699 set the access and modification times associated with file
1700 <Literal>path</Literal> to the current time.
1701 </Para>
1702
1703 <Para>
1704
1705 <ProgramListing>
1706 getPathVar :: PathVar -&#62; FilePath -&#62; IO Limit
1707 </ProgramListing>
1708
1709 </Para>
1710
1711 <Para>
1712 <Literal>getPathVar var path</Literal> calls <Function>pathconf</Function> to obtain the
1713 dynamic value of the requested configurable file limit or option associated
1714 with file or directory <Literal>path</Literal>.  For
1715 defined file limits, <Function>getPathVar</Function> returns the associated
1716 value.  For defined file options, the result of <Function>getPathVar</Function>
1717 is undefined, but not failure.
1718 The operation may fail with:
1719 <VariableList>
1720
1721 <VarListEntry>
1722 <Term><Literal>NoSuchThing</Literal></Term>
1723 <ListItem>
1724 <Para>
1725 The requested file limit or option is undefined.
1726 </Para>
1727 </ListItem>
1728 </VarListEntry>
1729 <VarListEntry>
1730 <Term><Literal>SystemError</Literal></Term>
1731 <ListItem>
1732 <Para>
1733 Various other causes.
1734 </Para>
1735 </ListItem>
1736 </VarListEntry>
1737 </VariableList>
1738 </Para>
1739
1740 <Para>
1741
1742 <ProgramListing>
1743 getFdVar :: PathVar -&#62; Fd -&#62; IO Limit
1744 </ProgramListing>
1745
1746 </Para>
1747
1748 <Para>
1749 <Literal>getFdVar var fd</Literal> calls <Function>fpathconf</Function> to obtain the
1750 dynamic value of the requested configurable file limit or option associated
1751 with the file or directory attached to the open channel <Literal>fd</Literal>.
1752 For defined file limits, <Function>getFdVar</Function> returns the associated
1753 value.  For defined file options, the result of <Function>getFdVar</Function>
1754 is undefined, but not failure.
1755 </Para>
1756
1757 <Para>
1758 The operation may fail with:
1759 </Para>
1760
1761 <Para>
1762 <VariableList>
1763
1764 <VarListEntry>
1765 <Term><Literal>NoSuchThing</Literal></Term>
1766 <ListItem>
1767 <Para>
1768 The requested file limit or option is undefined.
1769 </Para>
1770 </ListItem>
1771 </VarListEntry>
1772 <VarListEntry>
1773 <Term><Literal>SystemError</Literal></Term>
1774 <ListItem>
1775 <Para>
1776 Various other causes.
1777 </Para>
1778 </ListItem>
1779 </VarListEntry>
1780 </VariableList>
1781 </Para>
1782
1783 </Sect2>
1784
1785 <Sect2 id="Input-Output">
1786 <Title>Posix Input and Output Primitives
1787 </Title>
1788
1789 <Para>
1790 <IndexTerm><Primary>Posix, input/output</Primary></IndexTerm>
1791 </Para>
1792
1793 <Para>
1794
1795 <ProgramListing>
1796 createPipe :: IO (Fd, Fd)
1797 </ProgramListing>
1798
1799 </Para>
1800
1801 <Para>
1802 <Function>createPipe</Function> calls <Function>pipe</Function> to create a pipe and returns a pair of
1803 <Literal>Fd</Literal>s, the first for reading and the second for writing.
1804 </Para>
1805
1806 <Para>
1807
1808 <ProgramListing>
1809 dup :: Fd -&#62; IO Fd
1810 </ProgramListing>
1811
1812 </Para>
1813
1814 <Para>
1815 <Literal>dup fd</Literal> calls <Function>dup</Function> to duplicate <Literal>Fd</Literal> <Literal>fd</Literal> to
1816 another <Literal>Fd</Literal>.
1817 </Para>
1818
1819 <Para>
1820
1821 <ProgramListing>
1822 dupTo :: Fd -&#62; Fd -&#62; IO ()
1823 </ProgramListing>
1824
1825 </Para>
1826
1827 <Para>
1828 <Literal>dupTo src dst</Literal> calls <Function>dup2</Function> to duplicate <Literal>Fd</Literal>
1829 <Literal>src</Literal> to <Literal>Fd</Literal> <Literal>dst</Literal>.
1830 </Para>
1831
1832 <Para>
1833
1834 <ProgramListing>
1835 fdClose :: Fd -&#62; IO ()
1836 </ProgramListing>
1837
1838 </Para>
1839
1840 <Para>
1841 <Literal>fdClose fd</Literal> calls <Function>close</Function> to close <Literal>Fd</Literal> <Literal>fd</Literal>.
1842 </Para>
1843
1844 <Para>
1845
1846 <ProgramListing>
1847 fdRead :: Fd -&#62; ByteCount -&#62; IO (String, ByteCount)
1848 </ProgramListing>
1849
1850 </Para>
1851
1852 <Para>
1853 <Literal>fdRead fd nbytes</Literal> calls <Function>read</Function> to read at most <Literal>nbytes</Literal>
1854 bytes from <Literal>Fd</Literal> <Literal>fd</Literal>, and returns the result as a string
1855 paired with the number of bytes actually read.
1856 </Para>
1857
1858 <Para>
1859 The operation may fail with:
1860 </Para>
1861
1862 <Para>
1863 <VariableList>
1864
1865 <VarListEntry>
1866 <Term><Literal>EOF</Literal></Term>
1867 <ListItem>
1868 <Para>
1869 End of file has been reached.
1870 </Para>
1871 </ListItem>
1872 </VarListEntry>
1873 <VarListEntry>
1874 <Term><Literal>SystemError</Literal></Term>
1875 <ListItem>
1876 <Para>
1877 Various other causes.
1878 </Para>
1879 </ListItem>
1880 </VarListEntry>
1881 </VariableList>
1882 </Para>
1883
1884 <Para>
1885
1886 <ProgramListing>
1887 fdWrite :: Fd -&#62; String -&#62; IO ByteCount
1888 </ProgramListing>
1889
1890 </Para>
1891
1892 <Para>
1893 <Literal>fdWrite fd s</Literal> calls <Function>write</Function> to write
1894 the string <Literal>s</Literal> to <Literal>Fd</Literal> <Literal>fd</Literal> as a
1895 contiguous sequence of bytes.  It returns the number of bytes successfully
1896 written.
1897 </Para>
1898
1899 <Para>
1900
1901 <ProgramListing>
1902 queryFdOption :: FdOption -&#62; Fd -&#62; IO Bool
1903 </ProgramListing>
1904
1905 </Para>
1906
1907 <Para>
1908 <Literal>getFdOption opt fd</Literal> calls <Function>fcntl</Function> to determine whether or
1909 not the flag associated with <Literal>FdOption</Literal> <Literal>opt</Literal> is set for
1910 <Literal>Fd</Literal> <Literal>fd</Literal>.
1911 </Para>
1912
1913 <Para>
1914
1915 <ProgramListing>
1916 setFdOption :: Fd -&#62; FdOption -&#62; Bool -&#62; IO ()
1917 </ProgramListing>
1918
1919 </Para>
1920
1921 <Para>
1922 <Literal>setFdOption fd opt val</Literal> calls <Function>fcntl</Function> to set the flag
1923 associated with <Literal>FdOption</Literal> <Literal>opt</Literal> on <Literal>Fd</Literal> <Literal>fd</Literal> to
1924 <Literal>val</Literal>.
1925 </Para>
1926
1927 <Para>
1928
1929 <ProgramListing>
1930 getLock :: Fd -&#62; FileLock -&#62; IO (Maybe (ProcessID, FileLock))
1931 </ProgramListing>
1932
1933 </Para>
1934
1935 <Para>
1936 <Literal>getLock fd lock</Literal> calls <Function>fcntl</Function> to get the first <Literal>FileLock</Literal>
1937 for <Literal>Fd</Literal> <Literal>fd</Literal> which blocks the <Literal>FileLock</Literal> <Literal>lock</Literal>.  If
1938 no such <Literal>FileLock</Literal> exists, <Function>getLock</Function> returns <Literal>Nothing</Literal>.
1939 Otherwise, it returns <Literal>Just (pid, block)</Literal>, where <Literal>block</Literal> is the
1940 blocking <Literal>FileLock</Literal> and <Literal>pid</Literal> is the <Literal>ProcessID</Literal> of the
1941 process holding the blocking <Literal>FileLock</Literal>.
1942 </Para>
1943
1944 <Para>
1945
1946 <ProgramListing>
1947 setLock :: Fd -&#62; FileLock -&#62; IO ()
1948 </ProgramListing>
1949
1950 </Para>
1951
1952 <Para>
1953 <Literal>setLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F&lowbar;SETLK</Constant> to set or
1954 clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
1955 <Literal>FileLock</Literal> <Literal>lock</Literal>.  <Function>setLock</Function> does not block, but fails with
1956 <Literal>SystemError</Literal> if the request cannot be satisfied immediately.
1957 </Para>
1958
1959 <Para>
1960
1961 <ProgramListing>
1962 waitToSetLock :: Fd -&#62; FileLock -&#62; IO ()
1963 </ProgramListing>
1964
1965 </Para>
1966
1967 <Para>
1968 <Literal>waitToSetLock fd lock</Literal> calls <Function>fcntl</Function> with <Constant>F&lowbar;SETLKW</Constant> to set
1969 or clear a lock segment for <Literal>Fd</Literal> <Literal>fd</Literal> as indicated by the
1970 <Literal>FileLock</Literal> <Literal>lock</Literal>. If the request cannot be satisfied
1971 immediately, <Function>waitToSetLock</Function> blocks until the request can be
1972 satisfied.
1973 </Para>
1974
1975 <Para>
1976
1977 <ProgramListing>
1978 fdSeek :: Fd -&#62; SeekMode -&#62; FileOffset -&#62; IO FileOffset
1979 </ProgramListing>
1980
1981 </Para>
1982
1983 <Para>
1984 <Literal>fdSeek fd whence offset</Literal> calls <Function>lseek</Function> to position the
1985 <Literal>Fd</Literal> <Literal>fd</Literal> at the given <Literal>offset</Literal> from the starting location
1986 indicated by <Literal>whence</Literal>.  It returns the resulting offset from the
1987 start of the file in bytes.
1988 </Para>
1989
1990 </Sect2>
1991
1992 <Sect2 id="Device-Specific-Functions">
1993 <Title>Posix, Device- and Class-Specific Functions
1994 </Title>
1995
1996 <Para>
1997 <IndexTerm><Primary>Posix, device and class-specific functions</Primary></IndexTerm>
1998 </Para>
1999
2000 <Para>
2001
2002 <ProgramListing>
2003 terminalMode    :: TerminalMode -&#62; TerminalAttributes -&#62; Bool
2004 withMode        :: TerminalAttributes -&#62; TerminalMode -&#62; TerminalAttributes
2005 withoutMode     :: TerminalAttributes -&#62; TerminalMode -&#62; TerminalAttributes
2006
2007 bitsPerByte     :: TerminalAttributes -&#62; Int
2008 withBits        :: TerminalAttributes -&#62; Int -&#62; TerminalAttributes
2009
2010 controlChar     :: TerminalAttributes -&#62; ControlCharacter -&#62; Maybe Char
2011 withCC          :: TerminalAttributes
2012                 -&#62; (ControlCharacter, Char)
2013                 -&#62; TerminalAttributes
2014 withoutCC       :: TerminalAttributes
2015                 -&#62; ControlCharacter
2016                 -&#62; TerminalAttributes
2017
2018 inputTime       :: TerminalAttributes -&#62; Int
2019 withTime        :: TerminalAttributes -&#62; Int -&#62; TerminalAttributes
2020
2021 minInput        :: TerminalAttributes -&#62; Int
2022 withMinInput    :: TerminalAttributes -&#62; Int -&#62; TerminalAttributes
2023
2024 inputSpeed      :: TerminalAttributes -&#62; BaudRate
2025 withInputSpeed  :: TerminalAttributes -&#62; BaudRate -&#62; TerminalAttributes
2026
2027 outputSpeed     :: TerminalAttributes -&#62; BaudRate
2028 withOutputSpeed :: TerminalAttributes -&#62; BaudRate -&#62; TerminalAttributes
2029
2030 getTerminalAttributes :: Fd -&#62; IO TerminalAttributes
2031 </ProgramListing>
2032
2033 </Para>
2034
2035 <Para>
2036 <Literal>getTerminalAttributes fd</Literal> calls <Function>tcgetattr</Function> to obtain
2037 the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal>.
2038 </Para>
2039
2040 <Para>
2041
2042 <ProgramListing>
2043 setTerminalAttributes :: Fd
2044                       -&#62; TerminalAttributes
2045                       -&#62; TerminalState
2046                       -&#62; IO ()
2047 </ProgramListing>
2048
2049 </Para>
2050
2051 <Para>
2052 <Literal>setTerminalAttributes fd attr ts</Literal> calls <Function>tcsetattr</Function> to change
2053 the <Literal>TerminalAttributes</Literal> associated with <Literal>Fd</Literal> <Literal>fd</Literal> to
2054 <Literal>attr</Literal>, when the terminal is in the state indicated by <Literal>ts</Literal>.
2055 </Para>
2056
2057 <Para>
2058
2059 <ProgramListing>
2060 sendBreak :: Fd -&#62; Int -&#62; IO ()
2061 </ProgramListing>
2062
2063 </Para>
2064
2065 <Para>
2066 <Literal>sendBreak fd duration</Literal> calls <Function>tcsendbreak</Function> to transmit a
2067 continuous stream of zero-valued bits on <Literal>Fd</Literal> <Literal>fd</Literal> for the
2068 specified implementation-dependent <Literal>duration</Literal>.
2069 </Para>
2070
2071 <Para>
2072
2073 <ProgramListing>
2074 drainOutput :: Fd -&#62; IO ()
2075 </ProgramListing>
2076
2077 </Para>
2078
2079 <Para>
2080 <Literal>drainOutput fd</Literal> calls <Function>tcdrain</Function> to block until all output
2081 written to <Literal>Fd</Literal> <Literal>fd</Literal> has been transmitted.
2082 </Para>
2083
2084 <Para>
2085
2086 <ProgramListing>
2087 discardData :: Fd -&#62; QueueSelector -&#62; IO ()
2088 </ProgramListing>
2089
2090 </Para>
2091
2092 <Para>
2093 <Literal>discardData fd queues</Literal> calls <Function>tcflush</Function> to discard
2094 pending input and/or output for <Literal>Fd</Literal> <Literal>fd</Literal>,
2095 as indicated by the <Literal>QueueSelector</Literal> <Literal>queues</Literal>.
2096 </Para>
2097
2098 <Para>
2099
2100 <ProgramListing>
2101 controlFlow :: Fd -&#62; FlowAction -&#62; IO ()
2102 </ProgramListing>
2103
2104 </Para>
2105
2106 <Para>
2107 <Literal>controlFlow fd action</Literal> calls <Function>tcflow</Function> to control the
2108 flow of data on <Literal>Fd</Literal> <Literal>fd</Literal>, as indicated by
2109 <Literal>action</Literal>.
2110 </Para>
2111
2112 <Para>
2113
2114 <ProgramListing>
2115 getTerminalProcessGroupID :: Fd -&#62; IO ProcessGroupID
2116 </ProgramListing>
2117
2118 </Para>
2119
2120 <Para>
2121 <Literal>getTerminalProcessGroupID fd</Literal> calls <Function>tcgetpgrp</Function> to
2122 obtain the <Literal>ProcessGroupID</Literal> of the foreground process group
2123 associated with the terminal attached to <Literal>Fd</Literal> <Literal>fd</Literal>.
2124 </Para>
2125
2126 <Para>
2127
2128 <ProgramListing>
2129 setTerminalProcessGroupID :: Fd -&#62; ProcessGroupID -&#62; IO ()
2130 </ProgramListing>
2131
2132 </Para>
2133
2134 <Para>
2135 <Literal>setTerminalProcessGroupID fd pgid</Literal> calls <Function>tcsetpgrp</Function> to
2136 set the <Literal>ProcessGroupID</Literal> of the foreground process group
2137 associated with the terminal attached to <Literal>Fd</Literal>
2138 <Literal>fd</Literal> to <Literal>pgid</Literal>.
2139 </Para>
2140
2141 </Sect2>
2142
2143 <Sect2 id="System-Database">
2144 <Title>Posix System Databases
2145 </Title>
2146
2147 <Para>
2148 <IndexTerm><Primary>Posix, system databases</Primary></IndexTerm>
2149 </Para>
2150
2151 <Para>
2152
2153 <ProgramListing>
2154 groupName    :: GroupEntry -&#62; String
2155 groupID      :: GroupEntry -&#62; GroupID
2156 groupMembers :: GroupEntry -&#62; [String]
2157
2158 getGroupEntryForID :: GroupID -&#62; IO GroupEntry
2159 </ProgramListing>
2160
2161 </Para>
2162
2163 <Para>
2164 <Literal>getGroupEntryForID gid</Literal> calls <Function>getgrgid</Function> to obtain
2165 the <Literal>GroupEntry</Literal> information associated with <Literal>GroupID</Literal>
2166 <Literal>gid</Literal>.
2167 </Para>
2168
2169 <Para>
2170 The operation may fail with:
2171 </Para>
2172
2173 <Para>
2174 <VariableList>
2175
2176 <VarListEntry>
2177 <Term><Literal>NoSuchThing</Literal></Term>
2178 <ListItem>
2179 <Para>
2180 There is no group entry for the GroupID.
2181 </Para>
2182 </ListItem>
2183 </VarListEntry>
2184 </VariableList>
2185 </Para>
2186
2187 <Para>
2188
2189 <ProgramListing>
2190 getGroupEntryForName :: String -&#62; IO GroupEntry
2191 </ProgramListing>
2192
2193 </Para>
2194
2195 <Para>
2196 <Literal>getGroupEntryForName name</Literal> calls <Function>getgrnam</Function> to obtain
2197 the <Literal>GroupEntry</Literal> information associated with the group called
2198 <Literal>name</Literal>.
2199 </Para>
2200
2201 <Para>
2202 The operation may fail with:
2203 </Para>
2204
2205 <Para>
2206 <VariableList>
2207
2208 <VarListEntry>
2209 <Term><Literal>NoSuchThing</Literal></Term>
2210 <ListItem>
2211 <Para>
2212 There is no group entry for the name.
2213 </Para>
2214 </ListItem>
2215 </VarListEntry>
2216 </VariableList>
2217 </Para>
2218
2219 <Para>
2220
2221 <ProgramListing>
2222 userName      :: UserEntry -&#62; String
2223 userID        :: UserEntry -&#62; UserID
2224 userGroupID   :: UserEntry -&#62; GroupID
2225 homeDirectory :: UserEntry -&#62; String
2226 userShell     :: UserEntry -&#62; String
2227
2228 getUserEntryForID :: UserID -&#62; IO UserEntry
2229 </ProgramListing>
2230
2231 </Para>
2232
2233 <Para>
2234 <Literal>getUserEntryForID gid</Literal> calls <Function>getpwuid</Function> to obtain
2235 the <Literal>UserEntry</Literal> information associated with <Literal>UserID</Literal>
2236 <Literal>uid</Literal>.
2237 The operation may fail with:
2238 </Para>
2239
2240 <Para>
2241 <VariableList>
2242
2243 <VarListEntry>
2244 <Term><Literal>NoSuchThing</Literal></Term>
2245 <ListItem>
2246 <Para>
2247 There is no user entry for the UserID.
2248 </Para>
2249 </ListItem>
2250 </VarListEntry>
2251 </VariableList>
2252 </Para>
2253
2254 <Para>
2255
2256 <ProgramListing>
2257 getUserEntryForName :: String -&#62; IO UserEntry
2258 </ProgramListing>
2259
2260 </Para>
2261
2262 <Para>
2263 <Literal>getUserEntryForName name</Literal> calls <Function>getpwnam</Function> to obtain
2264 the <Literal>UserEntry</Literal> information associated with the user login
2265 <Literal>name</Literal>.
2266 </Para>
2267
2268 <Para>
2269 The operation may fail with:
2270 </Para>
2271
2272 <Para>
2273 <VariableList>
2274
2275 <VarListEntry>
2276 <Term><Literal>NoSuchThing</Literal></Term>
2277 <ListItem>
2278 <Para>
2279 There is no user entry for the name.
2280 </Para>
2281 </ListItem>
2282 </VarListEntry>
2283 </VariableList>
2284 </Para>
2285
2286 </Sect2>
2287
2288 <Sect2 id="Error-reporting-and-handling">
2289 <Title>POSIX Errors
2290 </Title>
2291
2292 <Para>
2293 <IndexTerm><Primary>Posix, errors</Primary></IndexTerm>
2294 </Para>
2295
2296 <Para>
2297
2298 <ProgramListing>
2299 getErrorCode :: IO ErrorCode
2300 </ProgramListing>
2301
2302 </Para>
2303
2304 <Para>
2305 <Function>getErrorCode</Function> returns the current value of the external
2306 variable <Function>errno</Function>.  It never fails.
2307 </Para>
2308
2309 <Para>
2310
2311 <ProgramListing>
2312 setErrorCode :: ErrorCode -&#62; IO ()
2313 </ProgramListing>
2314
2315 </Para>
2316
2317 <Para>
2318 <Literal>setErrorCode err</Literal> sets the external
2319 variable <Function>errno</Function> to <Literal>err</Literal>.  It never fails.
2320 </Para>
2321
2322 <Para>
2323
2324 <ProgramListing>
2325 noError :: ErrorCode
2326 noError = 0
2327
2328 argumentListTooLong, e2BIG              :: ErrorCode
2329 badFd, eBADF                            :: ErrorCode
2330 brokenPipe, ePIPE                       :: ErrorCode
2331 directoryNotEmpty, eNOTEMPTY            :: ErrorCode
2332 execFormatError, eNOEXEC                :: ErrorCode
2333 fileAlreadyExists, eEXIST               :: ErrorCode
2334 fileTooLarge, eFBIG                     :: ErrorCode
2335 filenameTooLong, eNAMETOOLONG           :: ErrorCode
2336 improperLink, eXDEV                     :: ErrorCode
2337 inappropriateIOControlOperation, eNOTTY :: ErrorCode
2338 inputOutputError, eIO                   :: ErrorCode
2339 interruptedOperation, eINTR             :: ErrorCode
2340 invalidArgument, eINVAL                 :: ErrorCode
2341 invalidSeek, eSPIPE                     :: ErrorCode
2342 isADirectory, eISDIR                    :: ErrorCode
2343 noChildProcess, eCHILD                  :: ErrorCode
2344 noLocksAvailable, eNOLCK                :: ErrorCode
2345 noSpaceLeftOnDevice, eNOSPC             :: ErrorCode
2346 noSuchOperationOnDevice, eNODEV         :: ErrorCode
2347 noSuchDeviceOrAddress, eNXIO            :: ErrorCode
2348 noSuchFileOrDirectory, eNOENT           :: ErrorCode
2349 noSuchProcess, eSRCH                    :: ErrorCode
2350 notADirectory, eNOTDIR                  :: ErrorCode
2351 notEnoughMemory, eNOMEM                 :: ErrorCode
2352 operationNotImplemented, eNOSYS         :: ErrorCode
2353 operationNotPermitted, ePERM            :: ErrorCode
2354 permissionDenied, eACCES                :: ErrorCode
2355 readOnlyFileSystem, eROFS               :: ErrorCode
2356 resourceBusy, eBUSY                     :: ErrorCode
2357 resourceDeadlockAvoided, eDEADLK        :: ErrorCode
2358 resourceTemporarilyUnavailable, eAGAIN  :: ErrorCode
2359 tooManyLinks, eMLINK                    :: ErrorCode
2360 tooManyOpenFiles, eMFILE                :: ErrorCode
2361 tooManyOpenFilesInSystem, eNFILE        :: ErrorCode
2362 </ProgramListing>
2363
2364 </Para>
2365
2366 </Sect2>
2367
2368 </Sect1>