ghc/docs/users_guide/posix.vsgml

   1 %************************************************************************
   2 %*                                                                      *
   3 <sect1>The Posix library
   4 <label id="Posix-library">
   5 <p>
   6 <nidx>Posix library</nidx>
   7 <nidx>libraries, Posix</nidx>
   8 %*                                                                      *
   9 %************************************************************************
  10
  11 The @Posix@ interface gives you access to the set of OS services
  12 standardised by POSIX 1003.1b (or the <em>IEEE Portable Operating System
  13 Interface for Computing Environments</em> - IEEE Std. 1003.1). The
  14 interface is accessed by @import Posix@ and adding
  15 @-syslib posix@ on your command-line.
  16
  17 <sect2>Posix data types
  18 <label id="Posix data types">
  19 <p>
  20 <nidx>Posix, data types</nidx>
  21
  22
  23 <tscreen><verb>
  24 data ByteCount  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  25 </verb></tscreen>
  26
  27 A @ByteCount@ is a primitive of type @unsigned@. At a minimum,
  28 an conforming implementation must support values in the range
  29 @[0, UINT_MAX]@.
  30
  31 <tscreen><verb>
  32 data ClockTick  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  33 </verb></tscreen>
  34
  35 A @ClockTick@ is a primitive of type @clock_t@, which
  36 is used to measure intervals of time in fractions of a second.  The
  37 resolution is determined by @getSysVar ClockTick@.
  38
  39 <tscreen><verb>
  40 data DeviceID  -- instances of : Eq Ord Num Real Integral Ix Enum Show
  41 </verb></tscreen>
  42
  43 A @DeviceID@ is a primitive of type @dev_t@.  It must
  44 be an arithmetic type.
  45
  46 <tscreen><verb>
  47 data EpochTime -- instances of : Eq Ord Num Real Integral Ix Enum Show
  48 </verb></tscreen>
  49
  50 A @EpochTime@ is a primitive of type @time_t@, which is
  51 used to measure seconds since the Epoch.  At a minimum, the implementation
  52 must support values in the range @[0, INT_MAX]@.
  53
  54 <tscreen><verb>
  55 data FileID -- instances of : Eq Ord Num Real Integral Ix Enum Show
  56 </verb></tscreen>
  57
  58 A @FileID@ is a primitive of type @ino_t@.  It must
  59 be an arithmetic type.
  60
  61 <tscreen><verb>
  62 data FileMode -- instances of : Eq Ord Num Real Integral Ix Enum Show
  63 </verb></tscreen>
  64
  65 A @FileMode@ is a primitive of type @mode_t@.
  66 It must be an arithmetic type.
  67
  68 <tscreen><verb>
  69 data FileOffset -- instances of : Eq Ord Num Real Integral Ix Enum Show
  70 </verb></tscreen>
  71
  72 A @FileOffset@ is a primitive of type @off_t@.  It must
  73 be an arithmetic type.
  74
  75 <tscreen><verb>
  76 data GroupID -- instances of : Eq Ord Num Real Integral Ix Enum Show
  77 </verb></tscreen>
  78
  79 A @GroupID@ is a primitive of type @gid_t@.  It must
  80 be an arithmetic type.
  81 <tscreen><verb>
  82 data Limit -- instances of : Eq Ord Num Real Integral Ix Enum Show
  83 </verb></tscreen>
  84
  85 A @Limit@ is a primitive of type @long@.
  86 At a minimum, the implementation must support values in the range
  87 @[LONG_MIN, LONG_MAX]@.
  88
  89 <tscreen><verb>
  90 data LinkCount -- instances of : Eq Ord Num Real Integral Ix Enum Show
  91 </verb></tscreen>
  92
  93 A @LinkCount@ is a primitive of type @nlink_t@.  It must
  94 be an arithmetic type.
  95
  96 <tscreen><verb>
  97 data ProcessID -- instances of : Eq Ord Num Real Integral Ix Enum Show
  98 type ProcessGroupID = ProcessID
  99 </verb></tscreen>
 100
 101 A @ProcessID@ is a primitive of type @pid_t@.  It
 102 must be a signed arithmetic type.
 103 <tscreen><verb>
 104 data UserID -- instances of : Eq Ord Num Real Integral Ix Enum Show
 105 </verb></tscreen>
 106
 107 A @UserID@ is a primitive of type @uid_t@.  It
 108 must be an arithmetic type.
 109
 110 <tscreen><verb>
 111 data DirStream
 112 </verb></tscreen>
 113 A @DirStream@ is a primitive of type @DIR *@.
 114
 115 <tscreen><verb>
 116 data FileStatus
 117 </verb></tscreen>
 118 A @FileStatus@ is a primitive of type @struct stat@.
 119
 120 <tscreen><verb>
 121 data GroupEntry
 122 </verb></tscreen>
 123
 124 A @GroupEntry@ is a primitive of type @struct group@.
 125 <tscreen><verb>
 126 data ProcessTimes
 127 </verb></tscreen>
 128
 129 @ProcessTimes@ is a primitive structure containing a
 130 @clock_t@ and a @struct tms@.
 131
 132 <tscreen><verb>
 133 data SignalSet
 134 </verb></tscreen>
 135
 136 An @SignalSet@ is a primitive of type @sigset_t@.
 137
 138 <tscreen><verb>
 139 data SystemID
 140 </verb></tscreen>
 141
 142 A @SystemID@ is a primitive of type @struct utsname@.
 143
 144 <tscreen><verb>
 145 data TerminalAttributes
 146 </verb></tscreen>
 147 @TerminalAttributes@ is a primitive of type @struct termios@.
 148
 149 <tscreen><verb>
 150 data UserEntry
 151 </verb></tscreen>
 152
 153 A @UserEntry@ is a primitive of type @struct passwd@.
 154
 155 <tscreen><verb>
 156 data BaudRate = B0 | B50 | B75 | B110 | B134 | B150 | B200 | B300 | B600
 157               | B1200 | B1800 | B2400 | B4800 | B9600 | B19200 | B38400
 158               deriving (Eq, Show)
 159
 160 data Fd
 161
 162 intToFd :: Int -> Fd -- use with care.
 163
 164 data FdOption = AppendOnWrite
 165               | CloseOnExec
 166               | NonBlockingRead
 167
 168 data ControlCharacter = EndOfFile
 169                       | EndOfLine
 170                       | Erase
 171                       | Interrupt
 172                       | Kill
 173                       | Quit
 174                       | Suspend
 175                       | Start
 176                       | Stop
 177
 178 type ErrorCode = Int
 179
 180 type FileLock = (LockRequest, SeekMode, FileOffset, FileOffset)
 181 --                            whence    start       length
 182
 183 data FlowAction = SuspendOutput | RestartOutput | TransmitStop | TransmitStart
 184
 185 data Handler = Default | Ignore | Catch (IO ())
 186
 187 data LockRequest = ReadLock | WriteLock | Unlock
 188                  deriving (Eq, Show)
 189
 190 data OpenMode = ReadOnly | WriteOnly | ReadWrite
 191
 192 data PathVar = LinkLimit
 193              | InputLineLimit
 194              | InputQueueLimit
 195              | FileNameLimit
 196              | PathNameLimit
 197              | PipeBufferLimit
 198              | SetOwnerAndGroupIsRestricted
 199              | FileNamesAreNotTruncated
 200
 201 data QueueSelector = InputQueue | OutputQueue | BothQueues
 202
 203 type Signal = Int
 204
 205 data SysVar = ArgumentLimit
 206             | ChildLimit
 207             | ClockTick
 208             | GroupLimit
 209             | OpenFileLimit
 210             | PosixVersion
 211             | HasSavedIDs
 212             | HasJobControl
 213
 214 data TerminalMode = InterruptOnBreak       -- BRKINT
 215                 | MapCRtoLF                -- ICRNL
 216                 | IgnoreBreak              -- IGNBRK
 217                 | IgnoreCR                 -- IGNCR
 218                 | IgnoreParityErrors       -- IGNPAR
 219                 | MapLFtoCR                -- INLCR
 220                 | CheckParity              -- INPCK
 221                 | StripHighBit             -- ISTRIP
 222                 | StartStopInput           -- IXOFF
 223                 | StartStopOutput          -- IXON
 224                 | MarkParityErrors         -- PARMRK
 225                 | ProcessOutput            -- OPOST
 226                 | LocalMode                -- CLOCAL
 227                 | ReadEnable               -- CREAD
 228                 | TwoStopBits              -- CSTOPB
 229                 | HangupOnClose            -- HUPCL
 230                 | EnableParity             -- PARENB
 231                 | OddParity                -- PARODD
 232                 | EnableEcho               -- ECHO
 233                 | EchoErase                -- ECHOE
 234                 | EchoKill                 -- ECHOK
 235                 | EchoLF                   -- ECHONL
 236                 | ProcessInput             -- ICANON
 237                 | ExtendedFunctions        -- IEXTEN
 238                 | KeyboardInterrupts       -- ISIG
 239                 | NoFlushOnInterrupt       -- NOFLSH
 240                 | BackgroundWriteInterrupt -- TOSTOP
 241
 242 data TerminalState = Immediately | WhenDrained | WhenFlushed
 243
 244 data ProcessStatus = Exited ExitCode
 245                    | Terminated Signal
 246                    | Stopped Signal
 247                    deriving (Eq, Show)
 248 </verb></tscreen>
 249
 250 <sect2>Posix Process Primitives
 251 <label id="Process Primitives">
 252 <p>
 253
 254 <tscreen><verb>
 255 forkProcess :: IO (Maybe ProcessID)
 256 </verb></tscreen>
 257
 258 @forkProcess@ calls @fork@, returning
 259 @Just pid@ to the parent, where @pid@ is the
 260 ProcessID of the child, and returning @Nothing@ to the
 261 child.
 262
 263 <tscreen><verb>
 264 executeFile :: FilePath                   -- Command
 265             -> Bool                       -- Search PATH?
 266             -> [String]                   -- Arguments
 267             -> Maybe [(String, String)]   -- Environment
 268             -> IO ()
 269 </verb></tscreen>
 270
 271 @executeFile cmd args env@ calls one of the
 272 @execv*@ family, depending on whether or not the current
 273 PATH is to be searched for the command, and whether or not an
 274 environment is provided to supersede the process's current
 275 environment.  The basename (leading directory names suppressed) of
 276 the command is passed to @execv*@ as @arg[0]@;
 277 the argument list passed to @executeFile@ therefore begins
 278 with @arg[1]@.
 279
 280 <tscreen><verb>
 281 Search PATH?    Supersede environ?      Call
 282 ~~~~~~~~~~~~    ~~~~~~~~~~~~~~~~~~      ~~~~~~~
 283 False           False                   execv
 284 False           True                    execve
 285 True            False                   execvp
 286 True            True                    execvpe*
 287 </verb></tscreen>
 288
 289 Note that @execvpe@ is not provided by the POSIX standard, and must
 290 be written by hand.  Care must be taken to ensure that the search path
 291 is extracted from the original environment, and not from the
 292 environment to be passed on to the new image.
 293
 294 A successful @executeFile@ overlays the current process image with
 295 a new one, so it only returns on failure.
 296 <tscreen><verb>
 297 runProcess :: FilePath                    -- Command
 298            -> [String]                    -- Arguments
 299            -> Maybe [(String, String)]    -- Environment (Nothing -> Inherited)
 300            -> Maybe FilePath              -- Working directory (Nothing -> inherited)
 301            -> Maybe Handle                -- stdin  (Nothing -> inherited)
 302            -> Maybe Handle                -- stdout (Nothing -> inherited)
 303            -> Maybe Handle                -- stderr (Nothing -> inherited)
 304            -> IO ()
 305 </verb></tscreen>
 306
 307 @runProcess@ is our candidate for the high-level OS-independent
 308 primitive.
 309
 310 @runProcess cmd args env wd inhdl outhdl errhdl@ runs @cmd@
 311 (searching the current @PATH@) with arguments @args@.  If
 312 @env@ is @Just pairs@, the command is executed with the
 313 environment specified by @pairs@ of variables and values;
 314 otherwise, the command is executed with the current environment.  If
 315 @wd@ is @Just dir@, the command is executed with working
 316 directory @dir@; otherwise, the command is executed in the current
 317 working directory.  If @{in,out,err@hdl} is @Just handle@, the
 318 command is executed with the @Fd@ for @std{in,out,err@}
 319 attached to the specified @handle@; otherwise, the @Fd@ for
 320 @std{in,out,err@} is left unchanged.
 321
 322 <tscreen><verb>
 323 getProcessStatus :: Bool              -- Block?
 324                  -> Bool              -- Stopped processes?
 325                  -> ProcessID
 326                  -> IO (Maybe ProcessStatus)
 327 </verb></tscreen>
 328
 329 @getProcessStatus blk stopped pid@ calls @waitpid@, returning
 330 @Just tc@, the @ProcessStatus@ for process @pid@ if it is
 331 available, @Nothing@ otherwise.  If @blk@ is @False@, then
 332 @WNOHANG@ is set in the options for @waitpid@, otherwise not.
 333 If @stopped@ is @True@, then @WUNTRACED@ is set in the
 334 options for @waitpid@, otherwise not.
 335
 336 <tscreen><verb>
 337 getGroupProcessStatus :: Bool         -- Block?
 338                       -> Bool         -- Stopped processes?
 339                       -> ProcessGroupID
 340                       -> IO (Maybe (ProcessID, ProcessStatus))
 341 </verb></tscreen>
 342
 343 @getGroupProcessStatus blk stopped pgid@ calls @waitpid@,
 344 returning @Just (pid, tc)@, the @ProcessID@ and
 345 @ProcessStatus@ for any process in group @pgid@ if one is
 346 available, @Nothing@ otherwise.  If @blk@ is @False@, then
 347 @WNOHANG@ is set in the options for @waitpid@, otherwise not.
 348 If @stopped@ is @True@, then @WUNTRACED@ is set in the
 349 options for @waitpid@, otherwise not.
 350
 351 <tscreen><verb>
 352 getAnyProcessStatus :: Bool           -- Block?
 353                     -> Bool           -- Stopped processes?
 354                     -> IO (Maybe (ProcessID, ProcessStatus))
 355 </verb></tscreen>
 356
 357 @getAnyProcessStatus blk stopped@ calls @waitpid@, returning
 358 @Just (pid, tc)@, the @ProcessID@ and @ProcessStatus@ for any
 359 child process if one is available, @Nothing@ otherwise.  If
 360 @blk@ is @False@, then @WNOHANG@ is set in the options for
 361 @waitpid@, otherwise not.  If @stopped@ is @True@, then
 362 @WUNTRACED@ is set in the options for @waitpid@, otherwise not.
 363
 364 <tscreen><verb>
 365 exitImmediately :: ExitCode -> IO ()
 366 </verb></tscreen>
 367
 368 @exitImmediately status@ calls @_exit@ to terminate the process
 369 with the indicated exit @status@.
 370 The operation never returns.
 371
 372 <tscreen><verb>
 373 getEnvironment :: IO [(String, String)]
 374 </verb></tscreen>
 375
 376 @getEnvironment@ parses the environment variable mapping provided by
 377 @environ@, returning @(variable, value)@ pairs.
 378 The operation never fails.
 379
 380 <tscreen><verb>
 381 setEnvironment :: [(String, String)] -> IO ()
 382 </verb></tscreen>
 383
 384 @setEnvironment@ replaces the process environment with the provided
 385 mapping of @(variable, value)@ pairs.
 386
 387 <tscreen><verb>
 388 getEnvVar :: String -> IO String
 389 </verb></tscreen>
 390
 391 @getEnvVar var@ returns the value associated with variable @var@
 392 in the current environment (identical functionality provided through
 393 standard Haskell library function @System.getEnv@).
 394
 395 The operation may fail with:
 396
 397 <descrip>
 398 <tag>@NoSuchThing@</tag>
 399 The variable has no mapping in the current environment.
 400 </descrip>
 401
 402 <tscreen><verb>
 403 setEnvVar :: String -> String -> IO ()
 404 </verb></tscreen>
 405
 406 @setEnvVar var val@ sets the value associated with variable @var@
 407 in the current environment to be @val@.  Any previous mapping is
 408 superseded.
 409
 410 <tscreen><verb>
 411 removeEnvVar :: String -> IO ()
 412 </verb></tscreen>
 413
 414 @removeEnvVar var@ removes any value associated with variable @var@
 415 in the current environment.  Deleting a variable for which there is no mapping
 416 does not generate an error.
 417
 418 <tscreen><verb>
 419 nullSignal :: Signal
 420 nullSignal = 0
 421
 422 backgroundRead, sigTTIN        :: Signal
 423 backgroundWrite, sigTTOU       :: Signal
 424 continueProcess, sigCONT       :: Signal
 425 floatingPointException, sigFPE :: Signal
 426 illegalInstruction, sigILL     :: Signal
 427 internalAbort, sigABRT         :: Signal
 428 keyboardSignal, sigINT         :: Signal
 429 keyboardStop, sigTSTP          :: Signal
 430 keyboardTermination, sigQUIT   :: Signal
 431 killProcess, sigKILL           :: Signal
 432 lostConnection, sigHUP         :: Signal
 433 openEndedPipe, sigPIPE         :: Signal
 434 processStatusChanged, sigCHLD  :: Signal
 435 realTimeAlarm, sigALRM         :: Signal
 436 segmentationViolation, sigSEGV :: Signal
 437 softwareStop, sigSTOP          :: Signal
 438 softwareTermination, sigTERM   :: Signal
 439 userDefinedSignal1, sigUSR1    :: Signal
 440 userDefinedSignal2, sigUSR2    :: Signal
 441
 442 signalProcess :: Signal -> ProcessID -> IO ()
 443 </verb></tscreen>
 444
 445 @signalProcess int pid@ calls @kill@ to signal
 446 process @pid@ with interrupt signal @int@.
 447
 448 <tscreen><verb>
 449 raiseSignal :: Signal -> IO ()
 450 </verb></tscreen>
 451
 452 @raiseSignal int@ calls @kill@ to signal the current process
 453 with interrupt signal @int@.
 454
 455 <tscreen><verb>
 456 signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
 457 </verb></tscreen>
 458
 459 @signalProcessGroup int pgid@ calls @kill@ to signal
 460 all processes in group @pgid@ with interrupt signal @int@.
 461
 462 <tscreen><verb>
 463 setStoppedChildFlag :: Bool -> IO Bool
 464 </verb></tscreen>
 465
 466 @setStoppedChildFlag bool@ sets a flag which controls whether or
 467 not the @NOCLDSTOP@ option will be used the next time a signal
 468 handler is installed for @SIGCHLD@.  If @bool@ is @True@ (the
 469 default), @NOCLDSTOP@ will not be used; otherwise it will be.  The
 470 operation never fails.
 471
 472 <tscreen><verb>
 473 queryStoppedChildFlag :: IO Bool
 474 </verb></tscreen>
 475
 476 @queryStoppedChildFlag@ queries the flag which
 477 controls whether or not the @NOCLDSTOP@ option will be used
 478 the next time a signal handler is installed for @SIGCHLD@.
 479 If @NOCLDSTOP@ will be used, it returns @False@;
 480 otherwise (the default) it returns @True@.
 481 The operation never fails.
 482
 483 <tscreen><verb>
 484 emptySignalSet :: SignalSet
 485 fullSignalSet  :: SignalSet
 486 addSignal      :: Signal -> SignalSet -> SignalSet
 487 deleteSignal   :: Signal -> SignalSet -> SignalSet
 488 inSignalSet    :: Signal -> SignalSet -> Bool
 489
 490 installHandler :: Signal
 491                -> Handler
 492                -> Maybe SignalSet       -- other signals to block
 493                -> IO Handler            -- old handler
 494 </verb></tscreen>
 495
 496 @installHandler int handler iset@ calls @sigaction@ to install
 497 an interrupt handler for signal @int@.  If @handler@ is
 498 @Default@, @SIG_DFL@ is installed; if @handler@ is
 499 @Ignore@, @SIG_IGN@ is installed; if @handler@ is
 500 @Catch action@, a handler is installed which will invoke @action@ as a
 501 replacement for @main@.  If @iset@ is @Just s@, then the
 502 @sa_mask@ of the @sigaction@ structure is set to @s@;
 503 otherwise it is cleared.  The previously installed signal handler for
 504 @int@ is returned.
 505
 506 <tscreen><verb>
 507 getSignalMask :: IO SignalSet
 508 </verb></tscreen>
 509
 510 @getSignalMask@ calls @sigprocmask@ to determine the
 511 set of interrupts which are currently being blocked.
 512
 513 <tscreen><verb>
 514 setSignalMask :: SignalSet -> IO SignalSet
 515 </verb></tscreen>
 516
 517 @setSignalMask mask@ calls @sigprocmask@ with
 518 @SIG_SETMASK@ to block all interrupts in @mask@.  The
 519 previous set of blocked interrupts is returned.
 520
 521 <tscreen><verb>
 522 blockSignals :: SignalSet -> IO SignalSet
 523 </verb></tscreen>
 524
 525 @setSignalMask mask@ calls @sigprocmask@ with
 526 @SIG_BLOCK@ to add all interrupts in @mask@ to the
 527 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 528
 529 <tscreen><verb>
 530 unBlockSignals :: SignalSet -> IO SignalSet
 531 </verb></tscreen>
 532
 533 @setSignalMask mask@ calls @sigprocmask@ with
 534 @SIG_UNBLOCK@ to remove all interrupts in @mask@ from the
 535 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 536
 537 <tscreen><verb>
 538 getPendingSignals :: IO SignalSet
 539 </verb></tscreen>
 540
 541 @getPendingSignals@ calls @sigpending@ to obtain
 542 the set of interrupts which have been received but are currently blocked.
 543
 544 <tscreen><verb>
 545 awaitSignal :: Maybe SignalSet -> IO ()
 546 </verb></tscreen>
 547
 548 @awaitSignal iset@ suspends execution until an interrupt is received.
 549 If @iset@ is @Just s@, @awaitSignal@ calls
 550 @sigsuspend@, installing @s@ as the new signal mask before
 551 suspending execution; otherwise, it calls @pause@.  If successful,
 552 @awaitSignal@ does not return.
 553
 554 <tscreen><verb>
 555 scheduleAlarm :: Int -> IO Int
 556 </verb></tscreen>
 557
 558 @scheduleAlarm i@ calls @alarm@ to schedule a real time
 559 alarm at least @i@ seconds in the future.
 560
 561 <tscreen><verb>
 562 sleep :: Int -> IO ()
 563 </verb></tscreen>
 564
 565 @sleep i@ calls @sleep@ to suspend execution of the
 566 program until at least @i@ seconds have elapsed or a signal is
 567 received.
 568
 569 <sect2>Posix Process Environment
 570 <label id="Process Environment">
 571 <p>
 572 <nidx>Posix, process environment</nidx>
 573
 574 <tscreen><verb>
 575 getProcessID :: IO ProcessID
 576 </verb></tscreen>
 577
 578 @getProcessID@ calls @getpid@ to obtain the @ProcessID@ for
 579 the current process.
 580
 581 <tscreen><verb>
 582 getParentProcessID :: IO ProcessID
 583 </verb></tscreen>
 584
 585 @getProcessID@ calls @getppid@ to obtain the @ProcessID@ for
 586 the parent of the current process.
 587
 588 <tscreen><verb>
 589 getRealUserID :: IO UserID
 590 </verb></tscreen>
 591
 592 @getRealUserID@ calls @getuid@ to obtain the real @UserID@
 593 associated with the current process.
 594
 595 <tscreen><verb>
 596 getEffectiveUserID :: IO UserID
 597 </verb></tscreen>
 598
 599 @getRealUserID@ calls @geteuid@ to obtain the effective
 600 @UserID@ associated with the current process.
 601
 602 <tscreen><verb>
 603 setUserID :: UserID -> IO ()
 604 </verb></tscreen>
 605
 606 @setUserID uid@ calls @setuid@ to set the real, effective, and
 607 saved set-user-id associated with the current process to @uid@.
 608
 609 <tscreen><verb>
 610 getLoginName :: IO String
 611 </verb></tscreen>
 612
 613 @getLoginName@ calls @getlogin@ to obtain the login name
 614 associated with the current process.
 615
 616 <tscreen><verb>
 617 getRealGroupID :: IO GroupID
 618 </verb></tscreen>
 619
 620 @getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
 621 associated with the current process.
 622
 623 <tscreen><verb>
 624 getEffectiveGroupID :: IO GroupID
 625 </verb></tscreen>
 626
 627 @getEffectiveGroupID@ calls @getegid@ to obtain the effective
 628 @GroupID@ associated with the current process.
 629
 630 <tscreen><verb>
 631 setGroupID :: GroupID -> IO ()
 632 </verb></tscreen>
 633
 634 @setGroupID gid@ calls @setgid@ to set the real, effective, and
 635 saved set-group-id associated with the current process to @gid@.
 636
 637 <tscreen><verb>
 638 getGroups :: IO [GroupID]
 639 </verb></tscreen>
 640
 641 @getGroups@ calls @getgroups@ to obtain the list of
 642 supplementary @GroupID@s associated with the current process.
 643
 644 <tscreen><verb>
 645 getEffectiveUserName :: IO String
 646 </verb></tscreen>
 647
 648 @getEffectiveUserName@ calls @cuserid@ to obtain a name
 649 associated with the effective @UserID@ of the process.
 650
 651 <tscreen><verb>
 652 getProcessGroupID :: IO ProcessGroupID
 653 </verb></tscreen>
 654
 655 @getProcessGroupID@ calls @getpgrp@ to obtain the
 656 @ProcessGroupID@ for the current process.
 657
 658 <tscreen><verb>
 659 createProcessGroup :: ProcessID -> IO ProcessGroupID
 660 </verb></tscreen>
 661
 662 @createProcessGroup pid@ calls @setpgid@ to make
 663 process @pid@ a new process group leader.
 664
 665 <tscreen><verb>
 666 joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
 667 </verb></tscreen>
 668
 669 @joinProcessGroup pgid@ calls @setpgid@ to set the
 670 @ProcessGroupID@ of the current process to @pgid@.
 671
 672 <tscreen><verb>
 673 setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
 674 </verb></tscreen>
 675
 676 @setProcessGroupID pid pgid@ calls @setpgid@ to set the
 677 @ProcessGroupID@ for process @pid@ to @pgid@.
 678
 679 <tscreen><verb>
 680 createSession :: IO ProcessGroupID
 681 </verb></tscreen>
 682
 683 @createSession@ calls @setsid@ to create a new session
 684 with the current process as session leader.
 685
 686 <tscreen><verb>
 687 systemName :: SystemID -> String
 688 nodeName :: SystemID -> String
 689 release :: SystemID -> String
 690 version :: SystemID -> String
 691 machine :: SystemID -> String
 692
 693 getSystemID :: IO SystemID
 694 </verb></tscreen>
 695
 696 @getSystemID@ calls @uname@ to obtain information
 697 about the current operating system.
 698
 699 <tscreen><verb>
 700 > epochTime :: IO EpochTime
 701 </verb></tscreen>
 702
 703 @epochTime@ calls @time@ to obtain the number of
 704 seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
 705
 706 <tscreen><verb>
 707 elapsedTime     :: ProcessTimes -> ClockTick
 708 userTime        :: ProcessTimes -> ClockTick
 709 systemTime      :: ProcessTimes -> ClockTick
 710 childUserTime   :: ProcessTimes -> ClockTick
 711 childSystemTime :: ProcessTimes -> ClockTick
 712
 713 getProcessTimes :: IO ProcessTimes
 714 </verb></tscreen>
 715
 716 @getProcessTimes@ calls @times@ to obtain time-accounting
 717 information for the current process and its children.
 718
 719 <tscreen><verb>
 720 getControllingTerminalName :: IO FilePath
 721 </verb></tscreen>
 722
 723 @getControllingTerminalName@ calls @ctermid@ to obtain
 724 a name associated with the controlling terminal for the process.  If a
 725 controlling terminal exists,
 726 @getControllingTerminalName@ returns the name of the
 727 controlling terminal.
 728
 729 The operation may fail with:
 730
 731 <descrip>
 732 <tag>@NoSuchThing@</tag>
 733 There is no controlling terminal, or its name cannot be determined.
 734 <tag>@SystemError@</tag>
 735 Various other causes.
 736 </descrip>
 737
 738 <tscreen><verb>
 739 getTerminalName :: Fd -> IO FilePath
 740 </verb></tscreen>
 741
 742 @getTerminalName fd@ calls @ttyname@ to obtain a name associated
 743 with the terminal for @Fd@ @fd@. If @fd@ is associated
 744 with a terminal, @getTerminalName@ returns the name of the
 745 terminal.
 746
 747 The operation may fail with:
 748
 749 <descrip>
 750 <tag>@InappropriateType@</tag>
 751 The channel is not associated with a terminal.
 752 <tag>@NoSuchThing@</tag>
 753 The channel is associated with a terminal, but it has no name.
 754 <tag>@SystemError@</tag>
 755 Various other causes.
 756 </descrip>
 757
 758 <tscreen><verb>
 759 queryTerminal :: Fd -> IO Bool
 760 </verb></tscreen>
 761
 762 @queryTerminal fd@ calls @isatty@ to determine whether or
 763 not @Fd@ @fd@ is associated with a terminal.
 764
 765 <tscreen><verb>
 766 getSysVar :: SysVar -> IO Limit
 767 </verb></tscreen>
 768
 769 @getSysVar var@ calls @sysconf@ to obtain the
 770 dynamic value of the requested configurable system limit or option.
 771 For defined system limits, @getSysVar@ returns the associated
 772 value.  For defined system options, the result of @getSysVar@
 773 is undefined, but not failure.
 774
 775 The operation may fail with:
 776
 777 <descrip>
 778 <tag>@NoSuchThing@</tag>
 779 The requested system limit or option is undefined.
 780 </descrip>
 781
 782 <sect2>Posix operations on files and directories
 783 <label id="Files and Directories">
 784 <p>
 785 <nidx>Posix, files and directories</nidx>
 786
 787 <tscreen><verb>
 788 openDirStream :: FilePath -> IO DirStream
 789 </verb></tscreen>
 790
 791 @openDirStream dir@ calls @opendir@ to obtain a
 792 directory stream for @dir@.
 793
 794 <tscreen><verb>
 795 readDirStream :: DirStream -> IO String
 796 </verb></tscreen>
 797
 798 @readDirStream dp@ calls @readdir@ to obtain the
 799 next directory entry (@struct dirent@) for the open directory
 800 stream @dp@, and returns the @d_name@ member of that
 801 structure.
 802
 803 The operation may fail with:
 804
 805 <descrip>
 806 <tag>@EOF@</tag>
 807 End of file has been reached.
 808 <tag>@SystemError@</tag>
 809 Various other causes.
 810 </descrip>
 811
 812 <tscreen><verb>
 813 rewindDirStream :: DirStream -> IO ()
 814 </verb></tscreen>
 815
 816 @rewindDirStream dp@ calls @rewinddir@ to reposition
 817 the directory stream @dp@ at the beginning of the directory.
 818
 819 <tscreen><verb>
 820 closeDirStream :: DirStream -> IO ()
 821 </verb></tscreen>
 822
 823 @closeDirStream dp@ calls @closedir@ to close
 824 the directory stream @dp@.
 825
 826 <tscreen><verb>
 827 getWorkingDirectory :: IO FilePath
 828 </verb></tscreen>
 829
 830 @getWorkingDirectory@ calls @getcwd@ to obtain the name
 831 of the current working directory.
 832
 833 <tscreen><verb>
 834 changeWorkingDirectory :: FilePath -> IO ()
 835 </verb></tscreen>
 836
 837 @changeWorkingDirectory dir@ calls @chdir@ to change
 838 the current working directory to @dir@.
 839
 840 <tscreen><verb>
 841 nullFileMode       :: FileMode       -- ---------
 842 ownerReadMode      :: FileMode       -- r--------
 843 ownerWriteMode     :: FileMode       -- -w-------
 844 ownerExecuteMode   :: FileMode       -- --x------
 845 groupReadMode      :: FileMode       -- ---r-----
 846 groupWriteMode     :: FileMode       -- ----w----
 847 groupExecuteMode   :: FileMode       -- -----x---
 848 otherReadMode      :: FileMode       -- ------r--
 849 otherWriteMode     :: FileMode       -- -------w-
 850 otherExecuteMode   :: FileMode       -- --------x
 851 setUserIDMode      :: FileMode       -- --S------
 852 setGroupIDMode     :: FileMode       -- -----S---
 853
 854 stdFileMode        :: FileMode       -- rw-rw-rw-
 855
 856 ownerModes         :: FileMode       -- rwx------
 857 groupModes         :: FileMode       -- ---rwx---
 858 otherModes         :: FileMode       -- ------rwx
 859 accessModes        :: FileMode       -- rwxrwxrwx
 860
 861 unionFileModes     :: FileMode -> FileMode -> FileMode
 862 intersectFileModes :: FileMode -> FileMode -> FileMode
 863
 864 stdInput  :: Fd
 865 stdInput  = intToFd 0
 866
 867 stdOutput :: Fd
 868 stdOutput = intToFd 1
 869
 870 stdError  :: Fd
 871 stdError  = intToFd 2
 872
 873 data OpenFileFlags =
 874  OpenFileFlags {
 875     append    :: Bool,
 876     exclusive :: Bool,
 877     noctty    :: Bool,
 878     nonBlock  :: Bool,
 879     trunc     :: Bool
 880  }
 881
 882 openFd :: FilePath
 883        -> OpenMode
 884        -> Maybe FileMode  -- Just x => O_CREAT, Nothing => must exist
 885        -> OpenFileFlags
 886        -> IO Fd
 887 </verb></tscreen>
 888
 889 @openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)@ calls
 890 @open@ to obtain a @Fd@ for the file @path@ with access
 891 mode @acc@.  If @mode@ is @Just m@, the @O_CREAT@ flag is
 892 set and the file's permissions will be based on @m@ if it does not
 893 already exist; otherwise, the @O_CREAT@ flag is not set.  The
 894 arguments @app@, @excl@, @noctty@, @nonblock@, and
 895 @trunc@ control whether or not the flags @O_APPEND@,
 896 @O_EXCL@, @O_NOCTTY@, @O_NONBLOCK@, and @O_TRUNC@ are set,
 897 respectively.
 898
 899 <tscreen><verb>
 900 createFile :: FilePath -> FileMode -> IO Fd
 901 </verb></tscreen>
 902
 903 @createFile path mode@ calls @creat@ to obtain a @Fd@
 904 for file @path@, which will be created with permissions based on
 905 @mode@ if it does not already exist.
 906
 907 <tscreen><verb>
 908 setFileCreationMask :: FileMode -> IO FileMode
 909 </verb></tscreen>
 910
 911 @setFileCreationMask mode@ calls @umask@ to set
 912 the process's file creation mask to @mode@.  The previous file
 913 creation mask is returned.
 914
 915 <tscreen><verb>
 916 createLink :: FilePath -> FilePath -> IO ()
 917 </verb></tscreen>
 918
 919 @createLink old new@ calls @link@ to create a
 920 new path, @new@, linked to an existing file, @old@.
 921 <tscreen><verb>
 922 createDirectory :: FilePath -> FileMode -> IO ()
 923 </verb></tscreen>
 924
 925 @createDirectory dir mode@ calls @mkdir@ to
 926 create a new directory, @dir@, with permissions based on
 927 @mode@.
 928
 929 <tscreen><verb>
 930 createNamedPipe :: FilePath -> FileMode -> IO ()
 931 </verb></tscreen>
 932
 933 @createNamedPipe fifo mode@ calls @mkfifo@ to
 934 create a new named pipe, @fifo@, with permissions based on
 935 @mode@.
 936
 937 <tscreen><verb>
 938 removeLink :: FilePath -> IO ()
 939 </verb></tscreen>
 940
 941 @removeLink path@ calls @unlink@ to remove the link
 942 named @path@.
 943
 944 <tscreen><verb>
 945 removeDirectory :: FilePath -> IO ()
 946 </verb></tscreen>
 947
 948 @removeDirectory dir@ calls @rmdir@ to remove the
 949 directory named @dir@.
 950
 951 <tscreen><verb>
 952 rename :: FilePath -> FilePath -> IO ()
 953 </verb></tscreen>
 954
 955 @rename old new@ calls @rename@ to rename a
 956 file or directory from @old@ to @new@.
 957
 958 <tscreen><verb>
 959 fileMode          :: FileStatus -> FileMode
 960
 961 fileID            :: FileStatus -> FileID
 962 deviceID          :: FileStatus -> DeviceID
 963
 964 linkCount         :: FileStatus -> LinkCount
 965
 966 fileOwner         :: FileStatus -> UserID
 967 fileGroup         :: FileStatus -> GroupID
 968 fileSize          :: FileStatus -> FileOffset
 969
 970 accessTime        :: FileStatus -> EpochTime
 971 modificationTime  :: FileStatus -> EpochTime
 972 statusChangeTime  :: FileStatus -> EpochTime
 973
 974 isDirectory       :: FileStatus -> Bool
 975 isCharacterDevice :: FileStatus -> Bool
 976 isBlockDevice     :: FileStatus -> Bool
 977 isRegularFile     :: FileStatus -> Bool
 978 isNamedPipe       :: FileStatus -> Bool
 979
 980 getFileStatus     :: FilePath -> IO FileStatus
 981 </verb></tscreen>
 982
 983 @getFileStatus path@ calls @stat@ to get the
 984 @FileStatus@ information for the file @path@.
 985
 986 <tscreen><verb>
 987 getFdStatus :: Fd -> IO FileStatus
 988 </verb></tscreen>
 989
 990 @getFdStatus fd@ calls @fstat@ to get the
 991 @FileStatus@ information for the file associated with
 992 @Fd@ @fd@.
 993
 994 <tscreen><verb>
 995 queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
 996 </verb></tscreen>
 997
 998 @queryAccess path r w x@ calls @access@ to test the access
 999 permissions for file @path@.  The three arguments, @r@, @w@,
1000 and @x@ control whether or not @access@ is called with
1001 @R_OK@, @W_OK@, and @X_OK@ respectively.
1002
1003 <tscreen><verb>
1004 queryFile :: FilePath -> IO Bool
1005 </verb></tscreen>
1006
1007 @queryFile path@ calls @access@ with @F_OK@ to test for the
1008 existence for file @path@.
1009
1010 <tscreen><verb>
1011 setFileMode :: FilePath -> FileMode -> IO ()
1012 </verb></tscreen>
1013
1014 @setFileMode path mode@ calls @chmod@ to set the
1015 permission bits associated with file @path@ to @mode@.
1016
1017 <tscreen><verb>
1018 setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
1019 </verb></tscreen>
1020
1021 @setOwnerAndGroup path uid gid@ calls @chown@ to
1022 set the @UserID@ and @GroupID@ associated with file
1023 @path@ to @uid@ and @gid@, respectively.
1024
1025 <tscreen><verb>
1026 setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
1027 </verb></tscreen>
1028
1029 @setFileTimes path atime mtime@ calls @utime@ to
1030 set the access and modification times associated with file
1031 @path@ to @atime@ and @mtime@, respectively.
1032
1033 <tscreen><verb>
1034 touchFile :: FilePath -> IO ()
1035 </verb></tscreen>
1036
1037 @touchFile path@ calls @utime@ to
1038 set the access and modification times associated with file
1039 @path@ to the current time.
1040
1041 <tscreen><verb>
1042 getPathVar :: PathVar -> FilePath -> IO Limit
1043 </verb></tscreen>
1044
1045 @getPathVar var path@ calls @pathconf@ to obtain the
1046 dynamic value of the requested configurable file limit or option associated
1047 with file or directory @path@.  For
1048 defined file limits, @getPathVar@ returns the associated
1049 value.  For defined file options, the result of @getPathVar@
1050 is undefined, but not failure.
1051 The operation may fail with:
1052 <descrip>
1053 <tag>@NoSuchThing@</tag>
1054 The requested file limit or option is undefined.
1055 <tag>@SystemError@</tag>
1056 Various other causes.
1057 </descrip>
1058
1059
1060 <tscreen><verb>
1061 getFdVar :: PathVar -> Fd -> IO Limit
1062 </verb></tscreen>
1063
1064 @getFdVar var fd@ calls @fpathconf@ to obtain the
1065 dynamic value of the requested configurable file limit or option associated
1066 with the file or directory attached to the open channel @fd@.
1067 For defined file limits, @getFdVar@ returns the associated
1068 value.  For defined file options, the result of @getFdVar@
1069 is undefined, but not failure.
1070
1071 The operation may fail with:
1072
1073 <descrip>
1074 <tag>@NoSuchThing@</tag>
1075 The requested file limit or option is undefined.
1076 <tag>@SystemError@</tag>
1077 Various other causes.
1078 </descrip>
1079
1080 <sect2>Posix Input and Output Primitives
1081 <label id="Inut Output">
1082 <p>
1083 <nidx>Posix, input/output</nidx>
1084
1085 <tscreen><verb>
1086 createPipe :: IO (Fd, Fd)
1087 </verb></tscreen>
1088
1089 @createPipe@ calls @pipe@ to create a pipe and returns a pair of
1090 @Fd@s, the first for writing and the second for reading.
1091
1092 <tscreen><verb>
1093 dup :: Fd -> IO Fd
1094 </verb></tscreen>
1095
1096 @dup fd@ calls @dup@ to duplicate @Fd@ @fd@ to
1097 another @Fd@.
1098
1099 <tscreen><verb>
1100 dupTo :: Fd -> Fd -> IO ()
1101 </verb></tscreen>
1102
1103 @dupTo src dst@ calls @dup2@ to duplicate @Fd@
1104 @src@ to @Fd@ @dst@.
1105
1106 <tscreen><verb>
1107 fdClose :: Fd -> IO ()
1108 </verb></tscreen>
1109
1110 @fdClose fd@ calls @close@ to close @Fd@ @fd@.
1111
1112 <tscreen><verb>
1113 fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
1114 </verb></tscreen>
1115
1116 @fdRead fd nbytes@ calls @read@ to read at most @nbytes@
1117 bytes from @Fd@ @fd@, and returns the result as a string
1118 paired with the number of bytes actually read.
1119
1120 The operation may fail with:
1121
1122 <descrip>
1123 <tag>@EOF@</tag>
1124 End of file has been reached.
1125 <tag>@SystemError@</tag>
1126 Various other causes.
1127 </descrip>
1128
1129 <tscreen><verb>
1130 fdWrite :: Fd -> String -> IO ByteCount
1131 </verb></tscreen>
1132
1133 @fdWrite fd s@ calls @write@ to write
1134 the string @s@ to @Fd@ @fd@ as a
1135 contiguous sequence of bytes.  It returns the number of bytes successfully
1136 written.
1137
1138 <tscreen><verb>
1139 queryFdOption :: FdOption -> Fd -> IO Bool
1140 </verb></tscreen>
1141
1142 @getFdOption opt fd@ calls @fcntl@ to determine whether or
1143 not the flag associated with @FdOption@ @opt@ is set for
1144 @Fd@ @fd@.
1145
1146 <tscreen><verb>
1147 setFdOption :: Fd -> FdOption -> Bool -> IO ()
1148 </verb></tscreen>
1149
1150 @setFdOption fd opt val@ calls @fcntl@ to set the flag
1151 associated with @FdOption@ @opt@ on @Fd@ @fd@ to
1152 @val@.
1153
1154 <tscreen><verb>
1155 getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
1156 </verb></tscreen>
1157
1158 @getLock fd lock@ calls @fcntl@ to get the first @FileLock@
1159 for @Fd@ @fd@ which blocks the @FileLock@ @lock@.  If
1160 no such @FileLock@ exists, @getLock@ returns @Nothing@.
1161 Otherwise, it returns @Just (pid, block)@, where @block@ is the
1162 blocking @FileLock@ and @pid@ is the @ProcessID@ of the
1163 process holding the blocking @FileLock@.
1164
1165
1166 <tscreen><verb>
1167 setLock :: Fd -> FileLock -> IO ()
1168 </verb></tscreen>
1169
1170 @setLock fd lock@ calls @fcntl@ with @F_SETLK@ to set or
1171 clear a lock segment for @Fd@ @fd@ as indicated by the
1172 @FileLock@ @lock@.  @setLock@ does not block, but fails with
1173 @SystemError@ if the request cannot be satisfied immediately.
1174
1175 <tscreen><verb>
1176 waitToSetLock :: Fd -> FileLock -> IO ()
1177 </verb></tscreen>
1178
1179 @waitToSetLock fd lock@ calls @fcntl@ with @F_SETLKW@ to set
1180 or clear a lock segment for @Fd@ @fd@ as indicated by the
1181 @FileLock@ @lock@. If the request cannot be satisfied
1182 immediately, @waitToSetLock@ blocks until the request can be
1183 satisfied.
1184
1185
1186 <tscreen><verb>
1187 fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
1188 </verb></tscreen>
1189
1190 @fdSeek fd whence offset@ calls @lseek@ to position the
1191 @Fd@ @fd@ at the given @offset@ from the starting location
1192 indicated by @whence@.  It returns the resulting offset from the
1193 start of the file in bytes.
1194
1195 <sect2>Posix, Device- and Class-Specific Functions
1196 <label id="Device Specific Functions">
1197 <p>
1198 <nidx>Posix, device and class-specific functions</nidx>
1199
1200 <tscreen><verb>
1201 terminalMode    :: TerminalMode -> TerminalAttributes -> Bool
1202 withMode        :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1203 withoutMode     :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1204
1205 bitsPerByte     :: TerminalAttributes -> Int
1206 withBits        :: TerminalAttributes -> Int -> TerminalAttributes
1207
1208 controlChar     :: TerminalAttributes -> ControlCharacter -> Maybe Char
1209 withCC          :: TerminalAttributes
1210                 -> (ControlCharacter, Char)
1211                 -> TerminalAttributes
1212 withoutCC       :: TerminalAttributes
1213                 -> ControlCharacter
1214                 -> TerminalAttributes
1215
1216 inputTime       :: TerminalAttributes -> Int
1217 withTime        :: TerminalAttributes -> Int -> TerminalAttributes
1218
1219 minInput        :: TerminalAttributes -> Int
1220 withMinInput    :: TerminalAttributes -> Int -> TerminalAttributes
1221
1222 inputSpeed      :: TerminalAttributes -> BaudRate
1223 withInputSpeed  :: TerminalAttributes -> BaudRate -> TerminalAttributes
1224
1225 outputSpeed     :: TerminalAttributes -> BaudRate
1226 withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
1227
1228 getTerminalAttributes :: Fd -> IO TerminalAttributes
1229 </verb></tscreen>
1230
1231 @getTerminalAttributes fd@ calls @tcgetattr@ to obtain
1232 the @TerminalAttributes@ associated with @Fd@ @fd@.
1233
1234 <tscreen><verb>
1235 setTerminalAttributes :: Fd
1236                       -> TerminalAttributes
1237                       -> TerminalState
1238                       -> IO ()
1239 </verb></tscreen>
1240
1241 @setTerminalAttributes fd attr ts@ calls @tcsetattr@ to change
1242 the @TerminalAttributes@ associated with @Fd@ @fd@ to
1243 @attr@, when the terminal is in the state indicated by @ts@.
1244
1245 <tscreen><verb>
1246 sendBreak :: Fd -> Int -> IO ()
1247 </verb></tscreen>
1248
1249 @sendBreak fd duration@ calls @tcsendbreak@ to transmit a
1250 continuous stream of zero-valued bits on @Fd@ @fd@ for the
1251 specified implementation-dependent @duration@.
1252
1253 <tscreen><verb>
1254 drainOutput :: Fd -> IO ()
1255 </verb></tscreen>
1256
1257 @drainOutput fd@ calls @tcdrain@ to block until all output
1258 written to @Fd@ @fd@ has been transmitted.
1259
1260 <tscreen><verb>
1261 discardData :: Fd -> QueueSelector -> IO ()
1262 </verb></tscreen>
1263
1264 @discardData fd queues@ calls @tcflush@ to discard
1265 pending input and/or output for @Fd@ @fd@,
1266 as indicated by the @QueueSelector@ @queues@.
1267
1268 <tscreen><verb>
1269 controlFlow :: Fd -> FlowAction -> IO ()
1270 </verb></tscreen>
1271
1272 @controlFlow fd action@ calls @tcflow@ to control the
1273 flow of data on @Fd@ @fd@, as indicated by
1274 @action@.
1275
1276 <tscreen><verb>
1277 getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
1278 </verb></tscreen>
1279
1280 @getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
1281 obtain the @ProcessGroupID@ of the foreground process group
1282 associated with the terminal attached to @Fd@ @fd@.
1283
1284 <tscreen><verb>
1285 setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
1286 </verb></tscreen>
1287
1288 @setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
1289 set the @ProcessGroupID@ of the foreground process group
1290 associated with the terminal attached to @Fd@
1291 @fd@ to @pgid@.
1292
1293 <sect2>Posix System Databases
1294 <label id="System Database">
1295 <p>
1296 <nidx>Posix, system databases</nidx>
1297
1298 <tscreen><verb>
1299 groupName    :: GroupEntry -> String
1300 groupID      :: GroupEntry -> GroupID
1301 groupMembers :: GroupEntry -> [String]
1302
1303 getGroupEntryForID :: GroupID -> IO GroupEntry
1304 </verb></tscreen>
1305
1306 @getGroupEntryForID gid@ calls @getgrgid@ to obtain
1307 the @GroupEntry@ information associated with @GroupID@
1308 @gid@.
1309
1310 The operation may fail with:
1311
1312 <descrip>
1313 <tag>@NoSuchThing@</tag>
1314 There is no group entry for the GroupID.
1315 </descrip>
1316
1317 <tscreen><verb>
1318 getGroupEntryForName :: String -> IO GroupEntry
1319 </verb></tscreen>
1320
1321 @getGroupEntryForName name@ calls @getgrnam@ to obtain
1322 the @GroupEntry@ information associated with the group called
1323 @name@.
1324
1325 The operation may fail with:
1326
1327 <descrip>
1328 <tag>@NoSuchThing@</tag>
1329 There is no group entry for the name.
1330 </descrip>
1331
1332 <tscreen><verb>
1333 userName      :: UserEntry -> String
1334 userID        :: UserEntry -> UserID
1335 userGroupID   :: UserEntry -> GroupID
1336 homeDirectory :: UserEntry -> String
1337 userShell     :: UserEntry -> String
1338
1339 getUserEntryForID :: UserID -> IO UserEntry
1340 </verb></tscreen>
1341
1342 @getUserEntryForID gid@ calls @getpwuid@ to obtain
1343 the @UserEntry@ information associated with @UserID@
1344 @uid@.
1345 The operation may fail with:
1346
1347 <descrip>
1348 <tag>@NoSuchThing@</tag>
1349 There is no user entry for the UserID.
1350 </descrip>
1351
1352 <tscreen><verb>
1353 getUserEntryForName :: String -> IO UserEntry
1354 </verb></tscreen>
1355
1356 @getUserEntryForName name@ calls @getpwnam@ to obtain
1357 the @UserEntry@ information associated with the user login
1358 @name@.
1359
1360 The operation may fail with:
1361
1362 <descrip>
1363 <tag>@NoSuchThing@</tag>
1364 There is no user entry for the name.
1365 </descrip>
1366
1367 <sect2>POSIX Errors
1368 <label id="Error reporting and handling">
1369 <p>
1370 <nidx>Posix, errors</nidx>
1371
1372 <tscreen><verb>
1373 getErrorCode :: IO ErrorCode
1374 </verb></tscreen>
1375
1376 @getErrorCode@ returns the current value of the external
1377 variable @errno@.  It never fails.
1378
1379 <tscreen><verb>
1380 setErrorCode :: ErrorCode -> IO ()
1381 </verb></tscreen>
1382
1383 @setErrorCode err@ sets the external
1384 variable @errno@ to @err@.  It never fails.
1385
1386 <tscreen><verb>
1387 noError :: ErrorCode
1388 noError = 0
1389
1390 argumentListTooLong, e2BIG              :: ErrorCode
1391 badFd, eBADF                            :: ErrorCode
1392 brokenPipe, ePIPE                       :: ErrorCode
1393 directoryNotEmpty, eNOTEMPTY            :: ErrorCode
1394 execFormatError, eNOEXEC                :: ErrorCode
1395 fileAlreadyExists, eEXIST               :: ErrorCode
1396 fileTooLarge, eFBIG                     :: ErrorCode
1397 filenameTooLong, eNAMETOOLONG           :: ErrorCode
1398 improperLink, eXDEV                     :: ErrorCode
1399 inappropriateIOControlOperation, eNOTTY :: ErrorCode
1400 inputOutputError, eIO                   :: ErrorCode
1401 interruptedOperation, eINTR             :: ErrorCode
1402 invalidArgument, eINVAL                 :: ErrorCode
1403 invalidSeek, eSPIPE                     :: ErrorCode
1404 isADirectory, eISDIR                    :: ErrorCode
1405 noChildProcess, eCHILD                  :: ErrorCode
1406 noLocksAvailable, eNOLCK                :: ErrorCode
1407 noSpaceLeftOnDevice, eNOSPC             :: ErrorCode
1408 noSuchOperationOnDevice, eNODEV         :: ErrorCode
1409 noSuchDeviceOrAddress, eNXIO            :: ErrorCode
1410 noSuchFileOrDirectory, eNOENT           :: ErrorCode
1411 noSuchProcess, eSRCH                    :: ErrorCode
1412 notADirectory, eNOTDIR                  :: ErrorCode
1413 notEnoughMemory, eNOMEM                 :: ErrorCode
1414 operationNotImplemented, eNOSYS         :: ErrorCode
1415 operationNotPermitted, ePERM            :: ErrorCode
1416 permissionDenied, eACCES                :: ErrorCode
1417 readOnlyFileSystem, eROFS               :: ErrorCode
1418 resourceBusy, eBUSY                     :: ErrorCode
1419 resourceDeadlockAvoided, eDEADLK        :: ErrorCode
1420 resourceTemporarilyUnavailable, eAGAIN  :: ErrorCode
1421 tooManyLinks, eMLINK                    :: ErrorCode
1422 tooManyOpenFiles, eMFILE                :: ErrorCode
1423 tooManyOpenFilesInSystem, eNFILE        :: ErrorCode
1424
1425 </verb></tscreen>