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 NOTE: In general, sharing open files between parent and child
 295 processes is potential bug farm, and should be avoided unless you
 296 really depend on this `feature' of POSIX' @fork()@ semantics. Using
 297 Haskell, there's the extra complication that arguments to
 298 @executeFile@ might come from files that are read lazily (using
 299 @hGetContents@, or some such.) If this is the case, then for your own
 300 sanity, please ensure that the arguments to @executeFile@ have been
 301 fully evaluated before calling @forkProcess@ (followed by
 302 @executeFile@.) Consider yourself warned :-)
 303
 304 A successful @executeFile@ overlays the current process image with
 305 a new one, so it only returns on failure.
 306
 307 <tscreen><verb>
 308 runProcess :: FilePath                    -- Command
 309            -> [String]                    -- Arguments
 310            -> Maybe [(String, String)]    -- Environment (Nothing -> Inherited)
 311            -> Maybe FilePath              -- Working directory (Nothing -> inherited)
 312            -> Maybe Handle                -- stdin  (Nothing -> inherited)
 313            -> Maybe Handle                -- stdout (Nothing -> inherited)
 314            -> Maybe Handle                -- stderr (Nothing -> inherited)
 315            -> IO ()
 316 </verb></tscreen>
 317
 318 @runProcess@ is our candidate for the high-level OS-independent
 319 primitive.
 320
 321 @runProcess cmd args env wd inhdl outhdl errhdl@ runs @cmd@
 322 (searching the current @PATH@) with arguments @args@.  If
 323 @env@ is @Just pairs@, the command is executed with the
 324 environment specified by @pairs@ of variables and values;
 325 otherwise, the command is executed with the current environment.  If
 326 @wd@ is @Just dir@, the command is executed with working
 327 directory @dir@; otherwise, the command is executed in the current
 328 working directory.  If @{in,out,err@hdl} is @Just handle@, the
 329 command is executed with the @Fd@ for @std{in,out,err@}
 330 attached to the specified @handle@; otherwise, the @Fd@ for
 331 @std{in,out,err@} is left unchanged.
 332
 333 <tscreen><verb>
 334 getProcessStatus :: Bool              -- Block?
 335                  -> Bool              -- Stopped processes?
 336                  -> ProcessID
 337                  -> IO (Maybe ProcessStatus)
 338 </verb></tscreen>
 339
 340 @getProcessStatus blk stopped pid@ calls @waitpid@, returning
 341 @Just tc@, the @ProcessStatus@ for process @pid@ if it is
 342 available, @Nothing@ otherwise.  If @blk@ is @False@, then
 343 @WNOHANG@ is set in the options for @waitpid@, otherwise not.
 344 If @stopped@ is @True@, then @WUNTRACED@ is set in the
 345 options for @waitpid@, otherwise not.
 346
 347 <tscreen><verb>
 348 getGroupProcessStatus :: Bool         -- Block?
 349                       -> Bool         -- Stopped processes?
 350                       -> ProcessGroupID
 351                       -> IO (Maybe (ProcessID, ProcessStatus))
 352 </verb></tscreen>
 353
 354 @getGroupProcessStatus blk stopped pgid@ calls @waitpid@,
 355 returning @Just (pid, tc)@, the @ProcessID@ and
 356 @ProcessStatus@ for any process in group @pgid@ if one is
 357 available, @Nothing@ otherwise.  If @blk@ is @False@, then
 358 @WNOHANG@ is set in the options for @waitpid@, otherwise not.
 359 If @stopped@ is @True@, then @WUNTRACED@ is set in the
 360 options for @waitpid@, otherwise not.
 361
 362 <tscreen><verb>
 363 getAnyProcessStatus :: Bool           -- Block?
 364                     -> Bool           -- Stopped processes?
 365                     -> IO (Maybe (ProcessID, ProcessStatus))
 366 </verb></tscreen>
 367
 368 @getAnyProcessStatus blk stopped@ calls @waitpid@, returning
 369 @Just (pid, tc)@, the @ProcessID@ and @ProcessStatus@ for any
 370 child process if one is available, @Nothing@ otherwise.  If
 371 @blk@ is @False@, then @WNOHANG@ is set in the options for
 372 @waitpid@, otherwise not.  If @stopped@ is @True@, then
 373 @WUNTRACED@ is set in the options for @waitpid@, otherwise not.
 374
 375 <tscreen><verb>
 376 exitImmediately :: ExitCode -> IO ()
 377 </verb></tscreen>
 378
 379 @exitImmediately status@ calls @_exit@ to terminate the process
 380 with the indicated exit @status@.
 381 The operation never returns.
 382
 383 <tscreen><verb>
 384 getEnvironment :: IO [(String, String)]
 385 </verb></tscreen>
 386
 387 @getEnvironment@ parses the environment variable mapping provided by
 388 @environ@, returning @(variable, value)@ pairs.
 389 The operation never fails.
 390
 391 <tscreen><verb>
 392 setEnvironment :: [(String, String)] -> IO ()
 393 </verb></tscreen>
 394
 395 @setEnvironment@ replaces the process environment with the provided
 396 mapping of @(variable, value)@ pairs.
 397
 398 <tscreen><verb>
 399 getEnvVar :: String -> IO String
 400 </verb></tscreen>
 401
 402 @getEnvVar var@ returns the value associated with variable @var@
 403 in the current environment (identical functionality provided through
 404 standard Haskell library function @System.getEnv@).
 405
 406 The operation may fail with:
 407
 408 <descrip>
 409 <tag>@NoSuchThing@</tag>
 410 The variable has no mapping in the current environment.
 411 </descrip>
 412
 413 <tscreen><verb>
 414 setEnvVar :: String -> String -> IO ()
 415 </verb></tscreen>
 416
 417 @setEnvVar var val@ sets the value associated with variable @var@
 418 in the current environment to be @val@.  Any previous mapping is
 419 superseded.
 420
 421 <tscreen><verb>
 422 removeEnvVar :: String -> IO ()
 423 </verb></tscreen>
 424
 425 @removeEnvVar var@ removes any value associated with variable @var@
 426 in the current environment.  Deleting a variable for which there is no mapping
 427 does not generate an error.
 428
 429 <tscreen><verb>
 430 nullSignal :: Signal
 431 nullSignal = 0
 432
 433 backgroundRead, sigTTIN        :: Signal
 434 backgroundWrite, sigTTOU       :: Signal
 435 continueProcess, sigCONT       :: Signal
 436 floatingPointException, sigFPE :: Signal
 437 illegalInstruction, sigILL     :: Signal
 438 internalAbort, sigABRT         :: Signal
 439 keyboardSignal, sigINT         :: Signal
 440 keyboardStop, sigTSTP          :: Signal
 441 keyboardTermination, sigQUIT   :: Signal
 442 killProcess, sigKILL           :: Signal
 443 lostConnection, sigHUP         :: Signal
 444 openEndedPipe, sigPIPE         :: Signal
 445 processStatusChanged, sigCHLD  :: Signal
 446 realTimeAlarm, sigALRM         :: Signal
 447 segmentationViolation, sigSEGV :: Signal
 448 softwareStop, sigSTOP          :: Signal
 449 softwareTermination, sigTERM   :: Signal
 450 userDefinedSignal1, sigUSR1    :: Signal
 451 userDefinedSignal2, sigUSR2    :: Signal
 452
 453 signalProcess :: Signal -> ProcessID -> IO ()
 454 </verb></tscreen>
 455
 456 @signalProcess int pid@ calls @kill@ to signal
 457 process @pid@ with interrupt signal @int@.
 458
 459 <tscreen><verb>
 460 raiseSignal :: Signal -> IO ()
 461 </verb></tscreen>
 462
 463 @raiseSignal int@ calls @kill@ to signal the current process
 464 with interrupt signal @int@.
 465
 466 <tscreen><verb>
 467 signalProcessGroup :: Signal -> ProcessGroupID -> IO ()
 468 </verb></tscreen>
 469
 470 @signalProcessGroup int pgid@ calls @kill@ to signal
 471 all processes in group @pgid@ with interrupt signal @int@.
 472
 473 <tscreen><verb>
 474 setStoppedChildFlag :: Bool -> IO Bool
 475 </verb></tscreen>
 476
 477 @setStoppedChildFlag bool@ sets a flag which controls whether or
 478 not the @NOCLDSTOP@ option will be used the next time a signal
 479 handler is installed for @SIGCHLD@.  If @bool@ is @True@ (the
 480 default), @NOCLDSTOP@ will not be used; otherwise it will be.  The
 481 operation never fails.
 482
 483 <tscreen><verb>
 484 queryStoppedChildFlag :: IO Bool
 485 </verb></tscreen>
 486
 487 @queryStoppedChildFlag@ queries the flag which
 488 controls whether or not the @NOCLDSTOP@ option will be used
 489 the next time a signal handler is installed for @SIGCHLD@.
 490 If @NOCLDSTOP@ will be used, it returns @False@;
 491 otherwise (the default) it returns @True@.
 492 The operation never fails.
 493
 494 <tscreen><verb>
 495 emptySignalSet :: SignalSet
 496 fullSignalSet  :: SignalSet
 497 addSignal      :: Signal -> SignalSet -> SignalSet
 498 deleteSignal   :: Signal -> SignalSet -> SignalSet
 499 inSignalSet    :: Signal -> SignalSet -> Bool
 500
 501 installHandler :: Signal
 502                -> Handler
 503                -> Maybe SignalSet       -- other signals to block
 504                -> IO Handler            -- old handler
 505 </verb></tscreen>
 506
 507 @installHandler int handler iset@ calls @sigaction@ to install
 508 an interrupt handler for signal @int@.  If @handler@ is
 509 @Default@, @SIG_DFL@ is installed; if @handler@ is
 510 @Ignore@, @SIG_IGN@ is installed; if @handler@ is
 511 @Catch action@, a handler is installed which will invoke @action@ as a
 512 replacement for @main@.  If @iset@ is @Just s@, then the
 513 @sa_mask@ of the @sigaction@ structure is set to @s@;
 514 otherwise it is cleared.  The previously installed signal handler for
 515 @int@ is returned.
 516
 517 <tscreen><verb>
 518 getSignalMask :: IO SignalSet
 519 </verb></tscreen>
 520
 521 @getSignalMask@ calls @sigprocmask@ to determine the
 522 set of interrupts which are currently being blocked.
 523
 524 <tscreen><verb>
 525 setSignalMask :: SignalSet -> IO SignalSet
 526 </verb></tscreen>
 527
 528 @setSignalMask mask@ calls @sigprocmask@ with
 529 @SIG_SETMASK@ to block all interrupts in @mask@.  The
 530 previous set of blocked interrupts is returned.
 531
 532 <tscreen><verb>
 533 blockSignals :: SignalSet -> IO SignalSet
 534 </verb></tscreen>
 535
 536 @setSignalMask mask@ calls @sigprocmask@ with
 537 @SIG_BLOCK@ to add all interrupts in @mask@ to the
 538 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 539
 540 <tscreen><verb>
 541 unBlockSignals :: SignalSet -> IO SignalSet
 542 </verb></tscreen>
 543
 544 @setSignalMask mask@ calls @sigprocmask@ with
 545 @SIG_UNBLOCK@ to remove all interrupts in @mask@ from the
 546 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 547
 548 <tscreen><verb>
 549 getPendingSignals :: IO SignalSet
 550 </verb></tscreen>
 551
 552 @getPendingSignals@ calls @sigpending@ to obtain
 553 the set of interrupts which have been received but are currently blocked.
 554
 555 <tscreen><verb>
 556 awaitSignal :: Maybe SignalSet -> IO ()
 557 </verb></tscreen>
 558
 559 @awaitSignal iset@ suspends execution until an interrupt is received.
 560 If @iset@ is @Just s@, @awaitSignal@ calls
 561 @sigsuspend@, installing @s@ as the new signal mask before
 562 suspending execution; otherwise, it calls @pause@.  If successful,
 563 @awaitSignal@ does not return.
 564
 565 <tscreen><verb>
 566 scheduleAlarm :: Int -> IO Int
 567 </verb></tscreen>
 568
 569 @scheduleAlarm i@ calls @alarm@ to schedule a real time
 570 alarm at least @i@ seconds in the future.
 571
 572 <tscreen><verb>
 573 sleep :: Int -> IO ()
 574 </verb></tscreen>
 575
 576 @sleep i@ calls @sleep@ to suspend execution of the
 577 program until at least @i@ seconds have elapsed or a signal is
 578 received.
 579
 580 <sect2>Posix Process Environment
 581 <label id="Process Environment">
 582 <p>
 583 <nidx>Posix, process environment</nidx>
 584
 585 <tscreen><verb>
 586 getProcessID :: IO ProcessID
 587 </verb></tscreen>
 588
 589 @getProcessID@ calls @getpid@ to obtain the @ProcessID@ for
 590 the current process.
 591
 592 <tscreen><verb>
 593 getParentProcessID :: IO ProcessID
 594 </verb></tscreen>
 595
 596 @getProcessID@ calls @getppid@ to obtain the @ProcessID@ for
 597 the parent of the current process.
 598
 599 <tscreen><verb>
 600 getRealUserID :: IO UserID
 601 </verb></tscreen>
 602
 603 @getRealUserID@ calls @getuid@ to obtain the real @UserID@
 604 associated with the current process.
 605
 606 <tscreen><verb>
 607 getEffectiveUserID :: IO UserID
 608 </verb></tscreen>
 609
 610 @getRealUserID@ calls @geteuid@ to obtain the effective
 611 @UserID@ associated with the current process.
 612
 613 <tscreen><verb>
 614 setUserID :: UserID -> IO ()
 615 </verb></tscreen>
 616
 617 @setUserID uid@ calls @setuid@ to set the real, effective, and
 618 saved set-user-id associated with the current process to @uid@.
 619
 620 <tscreen><verb>
 621 getLoginName :: IO String
 622 </verb></tscreen>
 623
 624 @getLoginName@ calls @getlogin@ to obtain the login name
 625 associated with the current process.
 626
 627 <tscreen><verb>
 628 getRealGroupID :: IO GroupID
 629 </verb></tscreen>
 630
 631 @getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
 632 associated with the current process.
 633
 634 <tscreen><verb>
 635 getEffectiveGroupID :: IO GroupID
 636 </verb></tscreen>
 637
 638 @getEffectiveGroupID@ calls @getegid@ to obtain the effective
 639 @GroupID@ associated with the current process.
 640
 641 <tscreen><verb>
 642 setGroupID :: GroupID -> IO ()
 643 </verb></tscreen>
 644
 645 @setGroupID gid@ calls @setgid@ to set the real, effective, and
 646 saved set-group-id associated with the current process to @gid@.
 647
 648 <tscreen><verb>
 649 getGroups :: IO [GroupID]
 650 </verb></tscreen>
 651
 652 @getGroups@ calls @getgroups@ to obtain the list of
 653 supplementary @GroupID@s associated with the current process.
 654
 655 <tscreen><verb>
 656 getEffectiveUserName :: IO String
 657 </verb></tscreen>
 658
 659 @getEffectiveUserName@ calls @cuserid@ to obtain a name
 660 associated with the effective @UserID@ of the process.
 661
 662 <tscreen><verb>
 663 getProcessGroupID :: IO ProcessGroupID
 664 </verb></tscreen>
 665
 666 @getProcessGroupID@ calls @getpgrp@ to obtain the
 667 @ProcessGroupID@ for the current process.
 668
 669 <tscreen><verb>
 670 createProcessGroup :: ProcessID -> IO ProcessGroupID
 671 </verb></tscreen>
 672
 673 @createProcessGroup pid@ calls @setpgid@ to make
 674 process @pid@ a new process group leader.
 675
 676 <tscreen><verb>
 677 joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
 678 </verb></tscreen>
 679
 680 @joinProcessGroup pgid@ calls @setpgid@ to set the
 681 @ProcessGroupID@ of the current process to @pgid@.
 682
 683 <tscreen><verb>
 684 setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
 685 </verb></tscreen>
 686
 687 @setProcessGroupID pid pgid@ calls @setpgid@ to set the
 688 @ProcessGroupID@ for process @pid@ to @pgid@.
 689
 690 <tscreen><verb>
 691 createSession :: IO ProcessGroupID
 692 </verb></tscreen>
 693
 694 @createSession@ calls @setsid@ to create a new session
 695 with the current process as session leader.
 696
 697 <tscreen><verb>
 698 systemName :: SystemID -> String
 699 nodeName :: SystemID -> String
 700 release :: SystemID -> String
 701 version :: SystemID -> String
 702 machine :: SystemID -> String
 703
 704 getSystemID :: IO SystemID
 705 </verb></tscreen>
 706
 707 @getSystemID@ calls @uname@ to obtain information
 708 about the current operating system.
 709
 710 <tscreen><verb>
 711 > epochTime :: IO EpochTime
 712 </verb></tscreen>
 713
 714 @epochTime@ calls @time@ to obtain the number of
 715 seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
 716
 717 <tscreen><verb>
 718 elapsedTime     :: ProcessTimes -> ClockTick
 719 userTime        :: ProcessTimes -> ClockTick
 720 systemTime      :: ProcessTimes -> ClockTick
 721 childUserTime   :: ProcessTimes -> ClockTick
 722 childSystemTime :: ProcessTimes -> ClockTick
 723
 724 getProcessTimes :: IO ProcessTimes
 725 </verb></tscreen>
 726
 727 @getProcessTimes@ calls @times@ to obtain time-accounting
 728 information for the current process and its children.
 729
 730 <tscreen><verb>
 731 getControllingTerminalName :: IO FilePath
 732 </verb></tscreen>
 733
 734 @getControllingTerminalName@ calls @ctermid@ to obtain
 735 a name associated with the controlling terminal for the process.  If a
 736 controlling terminal exists,
 737 @getControllingTerminalName@ returns the name of the
 738 controlling terminal.
 739
 740 The operation may fail with:
 741
 742 <descrip>
 743 <tag>@NoSuchThing@</tag>
 744 There is no controlling terminal, or its name cannot be determined.
 745 <tag>@SystemError@</tag>
 746 Various other causes.
 747 </descrip>
 748
 749 <tscreen><verb>
 750 getTerminalName :: Fd -> IO FilePath
 751 </verb></tscreen>
 752
 753 @getTerminalName fd@ calls @ttyname@ to obtain a name associated
 754 with the terminal for @Fd@ @fd@. If @fd@ is associated
 755 with a terminal, @getTerminalName@ returns the name of the
 756 terminal.
 757
 758 The operation may fail with:
 759
 760 <descrip>
 761 <tag>@InappropriateType@</tag>
 762 The channel is not associated with a terminal.
 763 <tag>@NoSuchThing@</tag>
 764 The channel is associated with a terminal, but it has no name.
 765 <tag>@SystemError@</tag>
 766 Various other causes.
 767 </descrip>
 768
 769 <tscreen><verb>
 770 queryTerminal :: Fd -> IO Bool
 771 </verb></tscreen>
 772
 773 @queryTerminal fd@ calls @isatty@ to determine whether or
 774 not @Fd@ @fd@ is associated with a terminal.
 775
 776 <tscreen><verb>
 777 getSysVar :: SysVar -> IO Limit
 778 </verb></tscreen>
 779
 780 @getSysVar var@ calls @sysconf@ to obtain the
 781 dynamic value of the requested configurable system limit or option.
 782 For defined system limits, @getSysVar@ returns the associated
 783 value.  For defined system options, the result of @getSysVar@
 784 is undefined, but not failure.
 785
 786 The operation may fail with:
 787
 788 <descrip>
 789 <tag>@NoSuchThing@</tag>
 790 The requested system limit or option is undefined.
 791 </descrip>
 792
 793 <sect2>Posix operations on files and directories
 794 <label id="Files and Directories">
 795 <p>
 796 <nidx>Posix, files and directories</nidx>
 797
 798 <tscreen><verb>
 799 openDirStream :: FilePath -> IO DirStream
 800 </verb></tscreen>
 801
 802 @openDirStream dir@ calls @opendir@ to obtain a
 803 directory stream for @dir@.
 804
 805 <tscreen><verb>
 806 readDirStream :: DirStream -> IO String
 807 </verb></tscreen>
 808
 809 @readDirStream dp@ calls @readdir@ to obtain the
 810 next directory entry (@struct dirent@) for the open directory
 811 stream @dp@, and returns the @d_name@ member of that
 812 structure.
 813
 814 The operation may fail with:
 815
 816 <descrip>
 817 <tag>@EOF@</tag>
 818 End of file has been reached.
 819 <tag>@SystemError@</tag>
 820 Various other causes.
 821 </descrip>
 822
 823 <tscreen><verb>
 824 rewindDirStream :: DirStream -> IO ()
 825 </verb></tscreen>
 826
 827 @rewindDirStream dp@ calls @rewinddir@ to reposition
 828 the directory stream @dp@ at the beginning of the directory.
 829
 830 <tscreen><verb>
 831 closeDirStream :: DirStream -> IO ()
 832 </verb></tscreen>
 833
 834 @closeDirStream dp@ calls @closedir@ to close
 835 the directory stream @dp@.
 836
 837 <tscreen><verb>
 838 getWorkingDirectory :: IO FilePath
 839 </verb></tscreen>
 840
 841 @getWorkingDirectory@ calls @getcwd@ to obtain the name
 842 of the current working directory.
 843
 844 <tscreen><verb>
 845 changeWorkingDirectory :: FilePath -> IO ()
 846 </verb></tscreen>
 847
 848 @changeWorkingDirectory dir@ calls @chdir@ to change
 849 the current working directory to @dir@.
 850
 851 <tscreen><verb>
 852 nullFileMode       :: FileMode       -- ---------
 853 ownerReadMode      :: FileMode       -- r--------
 854 ownerWriteMode     :: FileMode       -- -w-------
 855 ownerExecuteMode   :: FileMode       -- --x------
 856 groupReadMode      :: FileMode       -- ---r-----
 857 groupWriteMode     :: FileMode       -- ----w----
 858 groupExecuteMode   :: FileMode       -- -----x---
 859 otherReadMode      :: FileMode       -- ------r--
 860 otherWriteMode     :: FileMode       -- -------w-
 861 otherExecuteMode   :: FileMode       -- --------x
 862 setUserIDMode      :: FileMode       -- --S------
 863 setGroupIDMode     :: FileMode       -- -----S---
 864
 865 stdFileMode        :: FileMode       -- rw-rw-rw-
 866
 867 ownerModes         :: FileMode       -- rwx------
 868 groupModes         :: FileMode       -- ---rwx---
 869 otherModes         :: FileMode       -- ------rwx
 870 accessModes        :: FileMode       -- rwxrwxrwx
 871
 872 unionFileModes     :: FileMode -> FileMode -> FileMode
 873 intersectFileModes :: FileMode -> FileMode -> FileMode
 874
 875 stdInput  :: Fd
 876 stdInput  = intToFd 0
 877
 878 stdOutput :: Fd
 879 stdOutput = intToFd 1
 880
 881 stdError  :: Fd
 882 stdError  = intToFd 2
 883
 884 data OpenFileFlags =
 885  OpenFileFlags {
 886     append    :: Bool,
 887     exclusive :: Bool,
 888     noctty    :: Bool,
 889     nonBlock  :: Bool,
 890     trunc     :: Bool
 891  }
 892
 893 openFd :: FilePath
 894        -> OpenMode
 895        -> Maybe FileMode  -- Just x => O_CREAT, Nothing => must exist
 896        -> OpenFileFlags
 897        -> IO Fd
 898 </verb></tscreen>
 899
 900 @openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)@ calls
 901 @open@ to obtain a @Fd@ for the file @path@ with access
 902 mode @acc@.  If @mode@ is @Just m@, the @O_CREAT@ flag is
 903 set and the file's permissions will be based on @m@ if it does not
 904 already exist; otherwise, the @O_CREAT@ flag is not set.  The
 905 arguments @app@, @excl@, @noctty@, @nonblock@, and
 906 @trunc@ control whether or not the flags @O_APPEND@,
 907 @O_EXCL@, @O_NOCTTY@, @O_NONBLOCK@, and @O_TRUNC@ are set,
 908 respectively.
 909
 910 <tscreen><verb>
 911 createFile :: FilePath -> FileMode -> IO Fd
 912 </verb></tscreen>
 913
 914 @createFile path mode@ calls @creat@ to obtain a @Fd@
 915 for file @path@, which will be created with permissions based on
 916 @mode@ if it does not already exist.
 917
 918 <tscreen><verb>
 919 setFileCreationMask :: FileMode -> IO FileMode
 920 </verb></tscreen>
 921
 922 @setFileCreationMask mode@ calls @umask@ to set
 923 the process's file creation mask to @mode@.  The previous file
 924 creation mask is returned.
 925
 926 <tscreen><verb>
 927 createLink :: FilePath -> FilePath -> IO ()
 928 </verb></tscreen>
 929
 930 @createLink old new@ calls @link@ to create a
 931 new path, @new@, linked to an existing file, @old@.
 932 <tscreen><verb>
 933 createDirectory :: FilePath -> FileMode -> IO ()
 934 </verb></tscreen>
 935
 936 @createDirectory dir mode@ calls @mkdir@ to
 937 create a new directory, @dir@, with permissions based on
 938 @mode@.
 939
 940 <tscreen><verb>
 941 createNamedPipe :: FilePath -> FileMode -> IO ()
 942 </verb></tscreen>
 943
 944 @createNamedPipe fifo mode@ calls @mkfifo@ to
 945 create a new named pipe, @fifo@, with permissions based on
 946 @mode@.
 947
 948 <tscreen><verb>
 949 removeLink :: FilePath -> IO ()
 950 </verb></tscreen>
 951
 952 @removeLink path@ calls @unlink@ to remove the link
 953 named @path@.
 954
 955 <tscreen><verb>
 956 removeDirectory :: FilePath -> IO ()
 957 </verb></tscreen>
 958
 959 @removeDirectory dir@ calls @rmdir@ to remove the
 960 directory named @dir@.
 961
 962 <tscreen><verb>
 963 rename :: FilePath -> FilePath -> IO ()
 964 </verb></tscreen>
 965
 966 @rename old new@ calls @rename@ to rename a
 967 file or directory from @old@ to @new@.
 968
 969 <tscreen><verb>
 970 fileMode          :: FileStatus -> FileMode
 971
 972 fileID            :: FileStatus -> FileID
 973 deviceID          :: FileStatus -> DeviceID
 974
 975 linkCount         :: FileStatus -> LinkCount
 976
 977 fileOwner         :: FileStatus -> UserID
 978 fileGroup         :: FileStatus -> GroupID
 979 fileSize          :: FileStatus -> FileOffset
 980
 981 accessTime        :: FileStatus -> EpochTime
 982 modificationTime  :: FileStatus -> EpochTime
 983 statusChangeTime  :: FileStatus -> EpochTime
 984
 985 isDirectory       :: FileStatus -> Bool
 986 isCharacterDevice :: FileStatus -> Bool
 987 isBlockDevice     :: FileStatus -> Bool
 988 isRegularFile     :: FileStatus -> Bool
 989 isNamedPipe       :: FileStatus -> Bool
 990
 991 getFileStatus     :: FilePath -> IO FileStatus
 992 </verb></tscreen>
 993
 994 @getFileStatus path@ calls @stat@ to get the
 995 @FileStatus@ information for the file @path@.
 996
 997 <tscreen><verb>
 998 getFdStatus :: Fd -> IO FileStatus
 999 </verb></tscreen>
1000
1001 @getFdStatus fd@ calls @fstat@ to get the
1002 @FileStatus@ information for the file associated with
1003 @Fd@ @fd@.
1004
1005 <tscreen><verb>
1006 queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
1007 </verb></tscreen>
1008
1009 @queryAccess path r w x@ calls @access@ to test the access
1010 permissions for file @path@.  The three arguments, @r@, @w@,
1011 and @x@ control whether or not @access@ is called with
1012 @R_OK@, @W_OK@, and @X_OK@ respectively.
1013
1014 <tscreen><verb>
1015 queryFile :: FilePath -> IO Bool
1016 </verb></tscreen>
1017
1018 @queryFile path@ calls @access@ with @F_OK@ to test for the
1019 existence for file @path@.
1020
1021 <tscreen><verb>
1022 setFileMode :: FilePath -> FileMode -> IO ()
1023 </verb></tscreen>
1024
1025 @setFileMode path mode@ calls @chmod@ to set the
1026 permission bits associated with file @path@ to @mode@.
1027
1028 <tscreen><verb>
1029 setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
1030 </verb></tscreen>
1031
1032 @setOwnerAndGroup path uid gid@ calls @chown@ to
1033 set the @UserID@ and @GroupID@ associated with file
1034 @path@ to @uid@ and @gid@, respectively.
1035
1036 <tscreen><verb>
1037 setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
1038 </verb></tscreen>
1039
1040 @setFileTimes path atime mtime@ calls @utime@ to
1041 set the access and modification times associated with file
1042 @path@ to @atime@ and @mtime@, respectively.
1043
1044 <tscreen><verb>
1045 touchFile :: FilePath -> IO ()
1046 </verb></tscreen>
1047
1048 @touchFile path@ calls @utime@ to
1049 set the access and modification times associated with file
1050 @path@ to the current time.
1051
1052 <tscreen><verb>
1053 getPathVar :: PathVar -> FilePath -> IO Limit
1054 </verb></tscreen>
1055
1056 @getPathVar var path@ calls @pathconf@ to obtain the
1057 dynamic value of the requested configurable file limit or option associated
1058 with file or directory @path@.  For
1059 defined file limits, @getPathVar@ returns the associated
1060 value.  For defined file options, the result of @getPathVar@
1061 is undefined, but not failure.
1062 The operation may fail with:
1063 <descrip>
1064 <tag>@NoSuchThing@</tag>
1065 The requested file limit or option is undefined.
1066 <tag>@SystemError@</tag>
1067 Various other causes.
1068 </descrip>
1069
1070
1071 <tscreen><verb>
1072 getFdVar :: PathVar -> Fd -> IO Limit
1073 </verb></tscreen>
1074
1075 @getFdVar var fd@ calls @fpathconf@ to obtain the
1076 dynamic value of the requested configurable file limit or option associated
1077 with the file or directory attached to the open channel @fd@.
1078 For defined file limits, @getFdVar@ returns the associated
1079 value.  For defined file options, the result of @getFdVar@
1080 is undefined, but not failure.
1081
1082 The operation may fail with:
1083
1084 <descrip>
1085 <tag>@NoSuchThing@</tag>
1086 The requested file limit or option is undefined.
1087 <tag>@SystemError@</tag>
1088 Various other causes.
1089 </descrip>
1090
1091 <sect2>Posix Input and Output Primitives
1092 <label id="Input/Output">
1093 <p>
1094 <nidx>Posix, input/output</nidx>
1095
1096 <tscreen><verb>
1097 createPipe :: IO (Fd, Fd)
1098 </verb></tscreen>
1099
1100 @createPipe@ calls @pipe@ to create a pipe and returns a pair of
1101 @Fd@s, the first for reading and the second for writing.
1102
1103 <tscreen><verb>
1104 dup :: Fd -> IO Fd
1105 </verb></tscreen>
1106
1107 @dup fd@ calls @dup@ to duplicate @Fd@ @fd@ to
1108 another @Fd@.
1109
1110 <tscreen><verb>
1111 dupTo :: Fd -> Fd -> IO ()
1112 </verb></tscreen>
1113
1114 @dupTo src dst@ calls @dup2@ to duplicate @Fd@
1115 @src@ to @Fd@ @dst@.
1116
1117 <tscreen><verb>
1118 fdClose :: Fd -> IO ()
1119 </verb></tscreen>
1120
1121 @fdClose fd@ calls @close@ to close @Fd@ @fd@.
1122
1123 <tscreen><verb>
1124 fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
1125 </verb></tscreen>
1126
1127 @fdRead fd nbytes@ calls @read@ to read at most @nbytes@
1128 bytes from @Fd@ @fd@, and returns the result as a string
1129 paired with the number of bytes actually read.
1130
1131 The operation may fail with:
1132
1133 <descrip>
1134 <tag>@EOF@</tag>
1135 End of file has been reached.
1136 <tag>@SystemError@</tag>
1137 Various other causes.
1138 </descrip>
1139
1140 <tscreen><verb>
1141 fdWrite :: Fd -> String -> IO ByteCount
1142 </verb></tscreen>
1143
1144 @fdWrite fd s@ calls @write@ to write
1145 the string @s@ to @Fd@ @fd@ as a
1146 contiguous sequence of bytes.  It returns the number of bytes successfully
1147 written.
1148
1149 <tscreen><verb>
1150 queryFdOption :: FdOption -> Fd -> IO Bool
1151 </verb></tscreen>
1152
1153 @getFdOption opt fd@ calls @fcntl@ to determine whether or
1154 not the flag associated with @FdOption@ @opt@ is set for
1155 @Fd@ @fd@.
1156
1157 <tscreen><verb>
1158 setFdOption :: Fd -> FdOption -> Bool -> IO ()
1159 </verb></tscreen>
1160
1161 @setFdOption fd opt val@ calls @fcntl@ to set the flag
1162 associated with @FdOption@ @opt@ on @Fd@ @fd@ to
1163 @val@.
1164
1165 <tscreen><verb>
1166 getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
1167 </verb></tscreen>
1168
1169 @getLock fd lock@ calls @fcntl@ to get the first @FileLock@
1170 for @Fd@ @fd@ which blocks the @FileLock@ @lock@.  If
1171 no such @FileLock@ exists, @getLock@ returns @Nothing@.
1172 Otherwise, it returns @Just (pid, block)@, where @block@ is the
1173 blocking @FileLock@ and @pid@ is the @ProcessID@ of the
1174 process holding the blocking @FileLock@.
1175
1176
1177 <tscreen><verb>
1178 setLock :: Fd -> FileLock -> IO ()
1179 </verb></tscreen>
1180
1181 @setLock fd lock@ calls @fcntl@ with @F_SETLK@ to set or
1182 clear a lock segment for @Fd@ @fd@ as indicated by the
1183 @FileLock@ @lock@.  @setLock@ does not block, but fails with
1184 @SystemError@ if the request cannot be satisfied immediately.
1185
1186 <tscreen><verb>
1187 waitToSetLock :: Fd -> FileLock -> IO ()
1188 </verb></tscreen>
1189
1190 @waitToSetLock fd lock@ calls @fcntl@ with @F_SETLKW@ to set
1191 or clear a lock segment for @Fd@ @fd@ as indicated by the
1192 @FileLock@ @lock@. If the request cannot be satisfied
1193 immediately, @waitToSetLock@ blocks until the request can be
1194 satisfied.
1195
1196
1197 <tscreen><verb>
1198 fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
1199 </verb></tscreen>
1200
1201 @fdSeek fd whence offset@ calls @lseek@ to position the
1202 @Fd@ @fd@ at the given @offset@ from the starting location
1203 indicated by @whence@.  It returns the resulting offset from the
1204 start of the file in bytes.
1205
1206 <sect2>Posix, Device- and Class-Specific Functions
1207 <label id="Device Specific Functions">
1208 <p>
1209 <nidx>Posix, device and class-specific functions</nidx>
1210
1211 <tscreen><verb>
1212 terminalMode    :: TerminalMode -> TerminalAttributes -> Bool
1213 withMode        :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1214 withoutMode     :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1215
1216 bitsPerByte     :: TerminalAttributes -> Int
1217 withBits        :: TerminalAttributes -> Int -> TerminalAttributes
1218
1219 controlChar     :: TerminalAttributes -> ControlCharacter -> Maybe Char
1220 withCC          :: TerminalAttributes
1221                 -> (ControlCharacter, Char)
1222                 -> TerminalAttributes
1223 withoutCC       :: TerminalAttributes
1224                 -> ControlCharacter
1225                 -> TerminalAttributes
1226
1227 inputTime       :: TerminalAttributes -> Int
1228 withTime        :: TerminalAttributes -> Int -> TerminalAttributes
1229
1230 minInput        :: TerminalAttributes -> Int
1231 withMinInput    :: TerminalAttributes -> Int -> TerminalAttributes
1232
1233 inputSpeed      :: TerminalAttributes -> BaudRate
1234 withInputSpeed  :: TerminalAttributes -> BaudRate -> TerminalAttributes
1235
1236 outputSpeed     :: TerminalAttributes -> BaudRate
1237 withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
1238
1239 getTerminalAttributes :: Fd -> IO TerminalAttributes
1240 </verb></tscreen>
1241
1242 @getTerminalAttributes fd@ calls @tcgetattr@ to obtain
1243 the @TerminalAttributes@ associated with @Fd@ @fd@.
1244
1245 <tscreen><verb>
1246 setTerminalAttributes :: Fd
1247                       -> TerminalAttributes
1248                       -> TerminalState
1249                       -> IO ()
1250 </verb></tscreen>
1251
1252 @setTerminalAttributes fd attr ts@ calls @tcsetattr@ to change
1253 the @TerminalAttributes@ associated with @Fd@ @fd@ to
1254 @attr@, when the terminal is in the state indicated by @ts@.
1255
1256 <tscreen><verb>
1257 sendBreak :: Fd -> Int -> IO ()
1258 </verb></tscreen>
1259
1260 @sendBreak fd duration@ calls @tcsendbreak@ to transmit a
1261 continuous stream of zero-valued bits on @Fd@ @fd@ for the
1262 specified implementation-dependent @duration@.
1263
1264 <tscreen><verb>
1265 drainOutput :: Fd -> IO ()
1266 </verb></tscreen>
1267
1268 @drainOutput fd@ calls @tcdrain@ to block until all output
1269 written to @Fd@ @fd@ has been transmitted.
1270
1271 <tscreen><verb>
1272 discardData :: Fd -> QueueSelector -> IO ()
1273 </verb></tscreen>
1274
1275 @discardData fd queues@ calls @tcflush@ to discard
1276 pending input and/or output for @Fd@ @fd@,
1277 as indicated by the @QueueSelector@ @queues@.
1278
1279 <tscreen><verb>
1280 controlFlow :: Fd -> FlowAction -> IO ()
1281 </verb></tscreen>
1282
1283 @controlFlow fd action@ calls @tcflow@ to control the
1284 flow of data on @Fd@ @fd@, as indicated by
1285 @action@.
1286
1287 <tscreen><verb>
1288 getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
1289 </verb></tscreen>
1290
1291 @getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
1292 obtain the @ProcessGroupID@ of the foreground process group
1293 associated with the terminal attached to @Fd@ @fd@.
1294
1295 <tscreen><verb>
1296 setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
1297 </verb></tscreen>
1298
1299 @setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
1300 set the @ProcessGroupID@ of the foreground process group
1301 associated with the terminal attached to @Fd@
1302 @fd@ to @pgid@.
1303
1304 <sect2>Posix System Databases
1305 <label id="System Database">
1306 <p>
1307 <nidx>Posix, system databases</nidx>
1308
1309 <tscreen><verb>
1310 groupName    :: GroupEntry -> String
1311 groupID      :: GroupEntry -> GroupID
1312 groupMembers :: GroupEntry -> [String]
1313
1314 getGroupEntryForID :: GroupID -> IO GroupEntry
1315 </verb></tscreen>
1316
1317 @getGroupEntryForID gid@ calls @getgrgid@ to obtain
1318 the @GroupEntry@ information associated with @GroupID@
1319 @gid@.
1320
1321 The operation may fail with:
1322
1323 <descrip>
1324 <tag>@NoSuchThing@</tag>
1325 There is no group entry for the GroupID.
1326 </descrip>
1327
1328 <tscreen><verb>
1329 getGroupEntryForName :: String -> IO GroupEntry
1330 </verb></tscreen>
1331
1332 @getGroupEntryForName name@ calls @getgrnam@ to obtain
1333 the @GroupEntry@ information associated with the group called
1334 @name@.
1335
1336 The operation may fail with:
1337
1338 <descrip>
1339 <tag>@NoSuchThing@</tag>
1340 There is no group entry for the name.
1341 </descrip>
1342
1343 <tscreen><verb>
1344 userName      :: UserEntry -> String
1345 userID        :: UserEntry -> UserID
1346 userGroupID   :: UserEntry -> GroupID
1347 homeDirectory :: UserEntry -> String
1348 userShell     :: UserEntry -> String
1349
1350 getUserEntryForID :: UserID -> IO UserEntry
1351 </verb></tscreen>
1352
1353 @getUserEntryForID gid@ calls @getpwuid@ to obtain
1354 the @UserEntry@ information associated with @UserID@
1355 @uid@.
1356 The operation may fail with:
1357
1358 <descrip>
1359 <tag>@NoSuchThing@</tag>
1360 There is no user entry for the UserID.
1361 </descrip>
1362
1363 <tscreen><verb>
1364 getUserEntryForName :: String -> IO UserEntry
1365 </verb></tscreen>
1366
1367 @getUserEntryForName name@ calls @getpwnam@ to obtain
1368 the @UserEntry@ information associated with the user login
1369 @name@.
1370
1371 The operation may fail with:
1372
1373 <descrip>
1374 <tag>@NoSuchThing@</tag>
1375 There is no user entry for the name.
1376 </descrip>
1377
1378 <sect2>POSIX Errors
1379 <label id="Error reporting and handling">
1380 <p>
1381 <nidx>Posix, errors</nidx>
1382
1383 <tscreen><verb>
1384 getErrorCode :: IO ErrorCode
1385 </verb></tscreen>
1386
1387 @getErrorCode@ returns the current value of the external
1388 variable @errno@.  It never fails.
1389
1390 <tscreen><verb>
1391 setErrorCode :: ErrorCode -> IO ()
1392 </verb></tscreen>
1393
1394 @setErrorCode err@ sets the external
1395 variable @errno@ to @err@.  It never fails.
1396
1397 <tscreen><verb>
1398 noError :: ErrorCode
1399 noError = 0
1400
1401 argumentListTooLong, e2BIG              :: ErrorCode
1402 badFd, eBADF                            :: ErrorCode
1403 brokenPipe, ePIPE                       :: ErrorCode
1404 directoryNotEmpty, eNOTEMPTY            :: ErrorCode
1405 execFormatError, eNOEXEC                :: ErrorCode
1406 fileAlreadyExists, eEXIST               :: ErrorCode
1407 fileTooLarge, eFBIG                     :: ErrorCode
1408 filenameTooLong, eNAMETOOLONG           :: ErrorCode
1409 improperLink, eXDEV                     :: ErrorCode
1410 inappropriateIOControlOperation, eNOTTY :: ErrorCode
1411 inputOutputError, eIO                   :: ErrorCode
1412 interruptedOperation, eINTR             :: ErrorCode
1413 invalidArgument, eINVAL                 :: ErrorCode
1414 invalidSeek, eSPIPE                     :: ErrorCode
1415 isADirectory, eISDIR                    :: ErrorCode
1416 noChildProcess, eCHILD                  :: ErrorCode
1417 noLocksAvailable, eNOLCK                :: ErrorCode
1418 noSpaceLeftOnDevice, eNOSPC             :: ErrorCode
1419 noSuchOperationOnDevice, eNODEV         :: ErrorCode
1420 noSuchDeviceOrAddress, eNXIO            :: ErrorCode
1421 noSuchFileOrDirectory, eNOENT           :: ErrorCode
1422 noSuchProcess, eSRCH                    :: ErrorCode
1423 notADirectory, eNOTDIR                  :: ErrorCode
1424 notEnoughMemory, eNOMEM                 :: ErrorCode
1425 operationNotImplemented, eNOSYS         :: ErrorCode
1426 operationNotPermitted, ePERM            :: ErrorCode
1427 permissionDenied, eACCES                :: ErrorCode
1428 readOnlyFileSystem, eROFS               :: ErrorCode
1429 resourceBusy, eBUSY                     :: ErrorCode
1430 resourceDeadlockAvoided, eDEADLK        :: ErrorCode
1431 resourceTemporarilyUnavailable, eAGAIN  :: ErrorCode
1432 tooManyLinks, eMLINK                    :: ErrorCode
1433 tooManyOpenFiles, eMFILE                :: ErrorCode
1434 tooManyOpenFilesInSystem, eNFILE        :: ErrorCode
1435
1436 </verb></tscreen>