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 an
 508 interrupt handler for signal @int@.  If @handler@ is @Default@,
 509 @SIG_DFL@ is installed; if @handler@ is @Ignore@, @SIG_IGN@ is
 510 installed; if @handler@ is @Catch action@, a handler is installed
 511 which will invoke @action@ in a new thread when (or shortly after) the
 512 signal is received.  See Section <ref name="Concurrent Haskell"
 513 id="concurrent-haskell"> for details on how to communicate between
 514 threads.
 515
 516 If @iset@ is @Just s@, then the @sa_mask@ of the @sigaction@ structure
 517 is set to @s@; otherwise it is cleared.  The previously installed
 518 signal handler for @int@ is returned.
 519
 520 <tscreen><verb>
 521 getSignalMask :: IO SignalSet
 522 </verb></tscreen>
 523
 524 @getSignalMask@ calls @sigprocmask@ to determine the
 525 set of interrupts which are currently being blocked.
 526
 527 <tscreen><verb>
 528 setSignalMask :: SignalSet -> IO SignalSet
 529 </verb></tscreen>
 530
 531 @setSignalMask mask@ calls @sigprocmask@ with
 532 @SIG_SETMASK@ to block all interrupts in @mask@.  The
 533 previous set of blocked interrupts is returned.
 534
 535 <tscreen><verb>
 536 blockSignals :: SignalSet -> IO SignalSet
 537 </verb></tscreen>
 538
 539 @setSignalMask mask@ calls @sigprocmask@ with
 540 @SIG_BLOCK@ to add all interrupts in @mask@ to the
 541 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 542
 543 <tscreen><verb>
 544 unBlockSignals :: SignalSet -> IO SignalSet
 545 </verb></tscreen>
 546
 547 @setSignalMask mask@ calls @sigprocmask@ with
 548 @SIG_UNBLOCK@ to remove all interrupts in @mask@ from the
 549 set of blocked interrupts.  The previous set of blocked interrupts is returned.
 550
 551 <tscreen><verb>
 552 getPendingSignals :: IO SignalSet
 553 </verb></tscreen>
 554
 555 @getPendingSignals@ calls @sigpending@ to obtain
 556 the set of interrupts which have been received but are currently blocked.
 557
 558 <tscreen><verb>
 559 awaitSignal :: Maybe SignalSet -> IO ()
 560 </verb></tscreen>
 561
 562 @awaitSignal iset@ suspends execution until an interrupt is received.
 563 If @iset@ is @Just s@, @awaitSignal@ calls @sigsuspend@, installing
 564 @s@ as the new signal mask before suspending execution; otherwise, it
 565 calls @pause@.  @awaitSignal@ returns on receipt of a signal.  If you
 566 have installed any signal handlers with @installHandler@, it may be
 567 wise to call @yield@ directly after @awaitSignal@ to ensure that the
 568 signal handler runs as promptly.
 569
 570 <tscreen><verb>
 571 scheduleAlarm :: Int -> IO Int
 572 </verb></tscreen>
 573
 574 @scheduleAlarm i@ calls @alarm@ to schedule a real time
 575 alarm at least @i@ seconds in the future.
 576
 577 <tscreen><verb>
 578 sleep :: Int -> IO ()
 579 </verb></tscreen>
 580
 581 @sleep i@ calls @sleep@ to suspend execution of the
 582 program until at least @i@ seconds have elapsed or a signal is
 583 received.
 584
 585 <sect2>Posix Process Environment
 586 <label id="Process Environment">
 587 <p>
 588 <nidx>Posix, process environment</nidx>
 589
 590 <tscreen><verb>
 591 getProcessID :: IO ProcessID
 592 </verb></tscreen>
 593
 594 @getProcessID@ calls @getpid@ to obtain the @ProcessID@ for
 595 the current process.
 596
 597 <tscreen><verb>
 598 getParentProcessID :: IO ProcessID
 599 </verb></tscreen>
 600
 601 @getProcessID@ calls @getppid@ to obtain the @ProcessID@ for
 602 the parent of the current process.
 603
 604 <tscreen><verb>
 605 getRealUserID :: IO UserID
 606 </verb></tscreen>
 607
 608 @getRealUserID@ calls @getuid@ to obtain the real @UserID@
 609 associated with the current process.
 610
 611 <tscreen><verb>
 612 getEffectiveUserID :: IO UserID
 613 </verb></tscreen>
 614
 615 @getRealUserID@ calls @geteuid@ to obtain the effective
 616 @UserID@ associated with the current process.
 617
 618 <tscreen><verb>
 619 setUserID :: UserID -> IO ()
 620 </verb></tscreen>
 621
 622 @setUserID uid@ calls @setuid@ to set the real, effective, and
 623 saved set-user-id associated with the current process to @uid@.
 624
 625 <tscreen><verb>
 626 getLoginName :: IO String
 627 </verb></tscreen>
 628
 629 @getLoginName@ calls @getlogin@ to obtain the login name
 630 associated with the current process.
 631
 632 <tscreen><verb>
 633 getRealGroupID :: IO GroupID
 634 </verb></tscreen>
 635
 636 @getRealGroupID@ calls @getgid@ to obtain the real @GroupID@
 637 associated with the current process.
 638
 639 <tscreen><verb>
 640 getEffectiveGroupID :: IO GroupID
 641 </verb></tscreen>
 642
 643 @getEffectiveGroupID@ calls @getegid@ to obtain the effective
 644 @GroupID@ associated with the current process.
 645
 646 <tscreen><verb>
 647 setGroupID :: GroupID -> IO ()
 648 </verb></tscreen>
 649
 650 @setGroupID gid@ calls @setgid@ to set the real, effective, and
 651 saved set-group-id associated with the current process to @gid@.
 652
 653 <tscreen><verb>
 654 getGroups :: IO [GroupID]
 655 </verb></tscreen>
 656
 657 @getGroups@ calls @getgroups@ to obtain the list of
 658 supplementary @GroupID@s associated with the current process.
 659
 660 <tscreen><verb>
 661 getEffectiveUserName :: IO String
 662 </verb></tscreen>
 663
 664 @getEffectiveUserName@ calls @cuserid@ to obtain a name
 665 associated with the effective @UserID@ of the process.
 666
 667 <tscreen><verb>
 668 getProcessGroupID :: IO ProcessGroupID
 669 </verb></tscreen>
 670
 671 @getProcessGroupID@ calls @getpgrp@ to obtain the
 672 @ProcessGroupID@ for the current process.
 673
 674 <tscreen><verb>
 675 createProcessGroup :: ProcessID -> IO ProcessGroupID
 676 </verb></tscreen>
 677
 678 @createProcessGroup pid@ calls @setpgid@ to make
 679 process @pid@ a new process group leader.
 680
 681 <tscreen><verb>
 682 joinProcessGroup :: ProcessGroupID -> IO ProcessGroupID
 683 </verb></tscreen>
 684
 685 @joinProcessGroup pgid@ calls @setpgid@ to set the
 686 @ProcessGroupID@ of the current process to @pgid@.
 687
 688 <tscreen><verb>
 689 setProcessGroupID :: ProcessID -> ProcessGroupID -> IO ()
 690 </verb></tscreen>
 691
 692 @setProcessGroupID pid pgid@ calls @setpgid@ to set the
 693 @ProcessGroupID@ for process @pid@ to @pgid@.
 694
 695 <tscreen><verb>
 696 createSession :: IO ProcessGroupID
 697 </verb></tscreen>
 698
 699 @createSession@ calls @setsid@ to create a new session
 700 with the current process as session leader.
 701
 702 <tscreen><verb>
 703 systemName :: SystemID -> String
 704 nodeName :: SystemID -> String
 705 release :: SystemID -> String
 706 version :: SystemID -> String
 707 machine :: SystemID -> String
 708
 709 getSystemID :: IO SystemID
 710 </verb></tscreen>
 711
 712 @getSystemID@ calls @uname@ to obtain information
 713 about the current operating system.
 714
 715 <tscreen><verb>
 716 > epochTime :: IO EpochTime
 717 </verb></tscreen>
 718
 719 @epochTime@ calls @time@ to obtain the number of
 720 seconds that have elapsed since the epoch (Jan 01 00:00:00 GMT 1970).
 721
 722 <tscreen><verb>
 723 elapsedTime     :: ProcessTimes -> ClockTick
 724 userTime        :: ProcessTimes -> ClockTick
 725 systemTime      :: ProcessTimes -> ClockTick
 726 childUserTime   :: ProcessTimes -> ClockTick
 727 childSystemTime :: ProcessTimes -> ClockTick
 728
 729 getProcessTimes :: IO ProcessTimes
 730 </verb></tscreen>
 731
 732 @getProcessTimes@ calls @times@ to obtain time-accounting
 733 information for the current process and its children.
 734
 735 <tscreen><verb>
 736 getControllingTerminalName :: IO FilePath
 737 </verb></tscreen>
 738
 739 @getControllingTerminalName@ calls @ctermid@ to obtain
 740 a name associated with the controlling terminal for the process.  If a
 741 controlling terminal exists,
 742 @getControllingTerminalName@ returns the name of the
 743 controlling terminal.
 744
 745 The operation may fail with:
 746
 747 <descrip>
 748 <tag>@NoSuchThing@</tag>
 749 There is no controlling terminal, or its name cannot be determined.
 750 <tag>@SystemError@</tag>
 751 Various other causes.
 752 </descrip>
 753
 754 <tscreen><verb>
 755 getTerminalName :: Fd -> IO FilePath
 756 </verb></tscreen>
 757
 758 @getTerminalName fd@ calls @ttyname@ to obtain a name associated
 759 with the terminal for @Fd@ @fd@. If @fd@ is associated
 760 with a terminal, @getTerminalName@ returns the name of the
 761 terminal.
 762
 763 The operation may fail with:
 764
 765 <descrip>
 766 <tag>@InappropriateType@</tag>
 767 The channel is not associated with a terminal.
 768 <tag>@NoSuchThing@</tag>
 769 The channel is associated with a terminal, but it has no name.
 770 <tag>@SystemError@</tag>
 771 Various other causes.
 772 </descrip>
 773
 774 <tscreen><verb>
 775 queryTerminal :: Fd -> IO Bool
 776 </verb></tscreen>
 777
 778 @queryTerminal fd@ calls @isatty@ to determine whether or
 779 not @Fd@ @fd@ is associated with a terminal.
 780
 781 <tscreen><verb>
 782 getSysVar :: SysVar -> IO Limit
 783 </verb></tscreen>
 784
 785 @getSysVar var@ calls @sysconf@ to obtain the
 786 dynamic value of the requested configurable system limit or option.
 787 For defined system limits, @getSysVar@ returns the associated
 788 value.  For defined system options, the result of @getSysVar@
 789 is undefined, but not failure.
 790
 791 The operation may fail with:
 792
 793 <descrip>
 794 <tag>@NoSuchThing@</tag>
 795 The requested system limit or option is undefined.
 796 </descrip>
 797
 798 <sect2>Posix operations on files and directories
 799 <label id="Files and Directories">
 800 <p>
 801 <nidx>Posix, files and directories</nidx>
 802
 803 <tscreen><verb>
 804 openDirStream :: FilePath -> IO DirStream
 805 </verb></tscreen>
 806
 807 @openDirStream dir@ calls @opendir@ to obtain a
 808 directory stream for @dir@.
 809
 810 <tscreen><verb>
 811 readDirStream :: DirStream -> IO String
 812 </verb></tscreen>
 813
 814 @readDirStream dp@ calls @readdir@ to obtain the
 815 next directory entry (@struct dirent@) for the open directory
 816 stream @dp@, and returns the @d_name@ member of that
 817 structure.
 818
 819 The operation may fail with:
 820
 821 <descrip>
 822 <tag>@EOF@</tag>
 823 End of file has been reached.
 824 <tag>@SystemError@</tag>
 825 Various other causes.
 826 </descrip>
 827
 828 <tscreen><verb>
 829 rewindDirStream :: DirStream -> IO ()
 830 </verb></tscreen>
 831
 832 @rewindDirStream dp@ calls @rewinddir@ to reposition
 833 the directory stream @dp@ at the beginning of the directory.
 834
 835 <tscreen><verb>
 836 closeDirStream :: DirStream -> IO ()
 837 </verb></tscreen>
 838
 839 @closeDirStream dp@ calls @closedir@ to close
 840 the directory stream @dp@.
 841
 842 <tscreen><verb>
 843 getWorkingDirectory :: IO FilePath
 844 </verb></tscreen>
 845
 846 @getWorkingDirectory@ calls @getcwd@ to obtain the name
 847 of the current working directory.
 848
 849 <tscreen><verb>
 850 changeWorkingDirectory :: FilePath -> IO ()
 851 </verb></tscreen>
 852
 853 @changeWorkingDirectory dir@ calls @chdir@ to change
 854 the current working directory to @dir@.
 855
 856 <tscreen><verb>
 857 nullFileMode       :: FileMode       -- ---------
 858 ownerReadMode      :: FileMode       -- r--------
 859 ownerWriteMode     :: FileMode       -- -w-------
 860 ownerExecuteMode   :: FileMode       -- --x------
 861 groupReadMode      :: FileMode       -- ---r-----
 862 groupWriteMode     :: FileMode       -- ----w----
 863 groupExecuteMode   :: FileMode       -- -----x---
 864 otherReadMode      :: FileMode       -- ------r--
 865 otherWriteMode     :: FileMode       -- -------w-
 866 otherExecuteMode   :: FileMode       -- --------x
 867 setUserIDMode      :: FileMode       -- --S------
 868 setGroupIDMode     :: FileMode       -- -----S---
 869
 870 stdFileMode        :: FileMode       -- rw-rw-rw-
 871
 872 ownerModes         :: FileMode       -- rwx------
 873 groupModes         :: FileMode       -- ---rwx---
 874 otherModes         :: FileMode       -- ------rwx
 875 accessModes        :: FileMode       -- rwxrwxrwx
 876
 877 unionFileModes     :: FileMode -> FileMode -> FileMode
 878 intersectFileModes :: FileMode -> FileMode -> FileMode
 879
 880 stdInput  :: Fd
 881 stdInput  = intToFd 0
 882
 883 stdOutput :: Fd
 884 stdOutput = intToFd 1
 885
 886 stdError  :: Fd
 887 stdError  = intToFd 2
 888
 889 data OpenFileFlags =
 890  OpenFileFlags {
 891     append    :: Bool,
 892     exclusive :: Bool,
 893     noctty    :: Bool,
 894     nonBlock  :: Bool,
 895     trunc     :: Bool
 896  }
 897
 898 openFd :: FilePath
 899        -> OpenMode
 900        -> Maybe FileMode  -- Just x => O_CREAT, Nothing => must exist
 901        -> OpenFileFlags
 902        -> IO Fd
 903 </verb></tscreen>
 904
 905 @openFd path acc mode (OpenFileFlags app excl noctty nonblock trunc)@ calls
 906 @open@ to obtain a @Fd@ for the file @path@ with access
 907 mode @acc@.  If @mode@ is @Just m@, the @O_CREAT@ flag is
 908 set and the file's permissions will be based on @m@ if it does not
 909 already exist; otherwise, the @O_CREAT@ flag is not set.  The
 910 arguments @app@, @excl@, @noctty@, @nonblock@, and
 911 @trunc@ control whether or not the flags @O_APPEND@,
 912 @O_EXCL@, @O_NOCTTY@, @O_NONBLOCK@, and @O_TRUNC@ are set,
 913 respectively.
 914
 915 <tscreen><verb>
 916 createFile :: FilePath -> FileMode -> IO Fd
 917 </verb></tscreen>
 918
 919 @createFile path mode@ calls @creat@ to obtain a @Fd@
 920 for file @path@, which will be created with permissions based on
 921 @mode@ if it does not already exist.
 922
 923 <tscreen><verb>
 924 setFileCreationMask :: FileMode -> IO FileMode
 925 </verb></tscreen>
 926
 927 @setFileCreationMask mode@ calls @umask@ to set
 928 the process's file creation mask to @mode@.  The previous file
 929 creation mask is returned.
 930
 931 <tscreen><verb>
 932 createLink :: FilePath -> FilePath -> IO ()
 933 </verb></tscreen>
 934
 935 @createLink old new@ calls @link@ to create a
 936 new path, @new@, linked to an existing file, @old@.
 937 <tscreen><verb>
 938 createDirectory :: FilePath -> FileMode -> IO ()
 939 </verb></tscreen>
 940
 941 @createDirectory dir mode@ calls @mkdir@ to
 942 create a new directory, @dir@, with permissions based on
 943 @mode@.
 944
 945 <tscreen><verb>
 946 createNamedPipe :: FilePath -> FileMode -> IO ()
 947 </verb></tscreen>
 948
 949 @createNamedPipe fifo mode@ calls @mkfifo@ to
 950 create a new named pipe, @fifo@, with permissions based on
 951 @mode@.
 952
 953 <tscreen><verb>
 954 removeLink :: FilePath -> IO ()
 955 </verb></tscreen>
 956
 957 @removeLink path@ calls @unlink@ to remove the link
 958 named @path@.
 959
 960 <tscreen><verb>
 961 removeDirectory :: FilePath -> IO ()
 962 </verb></tscreen>
 963
 964 @removeDirectory dir@ calls @rmdir@ to remove the
 965 directory named @dir@.
 966
 967 <tscreen><verb>
 968 rename :: FilePath -> FilePath -> IO ()
 969 </verb></tscreen>
 970
 971 @rename old new@ calls @rename@ to rename a
 972 file or directory from @old@ to @new@.
 973
 974 <tscreen><verb>
 975 fileMode          :: FileStatus -> FileMode
 976
 977 fileID            :: FileStatus -> FileID
 978 deviceID          :: FileStatus -> DeviceID
 979
 980 linkCount         :: FileStatus -> LinkCount
 981
 982 fileOwner         :: FileStatus -> UserID
 983 fileGroup         :: FileStatus -> GroupID
 984 fileSize          :: FileStatus -> FileOffset
 985
 986 accessTime        :: FileStatus -> EpochTime
 987 modificationTime  :: FileStatus -> EpochTime
 988 statusChangeTime  :: FileStatus -> EpochTime
 989
 990 isDirectory       :: FileStatus -> Bool
 991 isCharacterDevice :: FileStatus -> Bool
 992 isBlockDevice     :: FileStatus -> Bool
 993 isRegularFile     :: FileStatus -> Bool
 994 isNamedPipe       :: FileStatus -> Bool
 995
 996 getFileStatus     :: FilePath -> IO FileStatus
 997 </verb></tscreen>
 998
 999 @getFileStatus path@ calls @stat@ to get the
1000 @FileStatus@ information for the file @path@.
1001
1002 <tscreen><verb>
1003 getFdStatus :: Fd -> IO FileStatus
1004 </verb></tscreen>
1005
1006 @getFdStatus fd@ calls @fstat@ to get the
1007 @FileStatus@ information for the file associated with
1008 @Fd@ @fd@.
1009
1010 <tscreen><verb>
1011 queryAccess :: FilePath -> Bool -> Bool -> Bool -> IO Bool
1012 </verb></tscreen>
1013
1014 @queryAccess path r w x@ calls @access@ to test the access
1015 permissions for file @path@.  The three arguments, @r@, @w@,
1016 and @x@ control whether or not @access@ is called with
1017 @R_OK@, @W_OK@, and @X_OK@ respectively.
1018
1019 <tscreen><verb>
1020 queryFile :: FilePath -> IO Bool
1021 </verb></tscreen>
1022
1023 @queryFile path@ calls @access@ with @F_OK@ to test for the
1024 existence for file @path@.
1025
1026 <tscreen><verb>
1027 setFileMode :: FilePath -> FileMode -> IO ()
1028 </verb></tscreen>
1029
1030 @setFileMode path mode@ calls @chmod@ to set the
1031 permission bits associated with file @path@ to @mode@.
1032
1033 <tscreen><verb>
1034 setOwnerAndGroup :: FilePath -> UserID -> GroupID -> IO ()
1035 </verb></tscreen>
1036
1037 @setOwnerAndGroup path uid gid@ calls @chown@ to
1038 set the @UserID@ and @GroupID@ associated with file
1039 @path@ to @uid@ and @gid@, respectively.
1040
1041 <tscreen><verb>
1042 setFileTimes :: FilePath -> EpochTime -> EpochTime -> IO ()
1043 </verb></tscreen>
1044
1045 @setFileTimes path atime mtime@ calls @utime@ to
1046 set the access and modification times associated with file
1047 @path@ to @atime@ and @mtime@, respectively.
1048
1049 <tscreen><verb>
1050 touchFile :: FilePath -> IO ()
1051 </verb></tscreen>
1052
1053 @touchFile path@ calls @utime@ to
1054 set the access and modification times associated with file
1055 @path@ to the current time.
1056
1057 <tscreen><verb>
1058 getPathVar :: PathVar -> FilePath -> IO Limit
1059 </verb></tscreen>
1060
1061 @getPathVar var path@ calls @pathconf@ to obtain the
1062 dynamic value of the requested configurable file limit or option associated
1063 with file or directory @path@.  For
1064 defined file limits, @getPathVar@ returns the associated
1065 value.  For defined file options, the result of @getPathVar@
1066 is undefined, but not failure.
1067 The operation may fail with:
1068 <descrip>
1069 <tag>@NoSuchThing@</tag>
1070 The requested file limit or option is undefined.
1071 <tag>@SystemError@</tag>
1072 Various other causes.
1073 </descrip>
1074
1075
1076 <tscreen><verb>
1077 getFdVar :: PathVar -> Fd -> IO Limit
1078 </verb></tscreen>
1079
1080 @getFdVar var fd@ calls @fpathconf@ to obtain the
1081 dynamic value of the requested configurable file limit or option associated
1082 with the file or directory attached to the open channel @fd@.
1083 For defined file limits, @getFdVar@ returns the associated
1084 value.  For defined file options, the result of @getFdVar@
1085 is undefined, but not failure.
1086
1087 The operation may fail with:
1088
1089 <descrip>
1090 <tag>@NoSuchThing@</tag>
1091 The requested file limit or option is undefined.
1092 <tag>@SystemError@</tag>
1093 Various other causes.
1094 </descrip>
1095
1096 <sect2>Posix Input and Output Primitives
1097 <label id="Input/Output">
1098 <p>
1099 <nidx>Posix, input/output</nidx>
1100
1101 <tscreen><verb>
1102 createPipe :: IO (Fd, Fd)
1103 </verb></tscreen>
1104
1105 @createPipe@ calls @pipe@ to create a pipe and returns a pair of
1106 @Fd@s, the first for reading and the second for writing.
1107
1108 <tscreen><verb>
1109 dup :: Fd -> IO Fd
1110 </verb></tscreen>
1111
1112 @dup fd@ calls @dup@ to duplicate @Fd@ @fd@ to
1113 another @Fd@.
1114
1115 <tscreen><verb>
1116 dupTo :: Fd -> Fd -> IO ()
1117 </verb></tscreen>
1118
1119 @dupTo src dst@ calls @dup2@ to duplicate @Fd@
1120 @src@ to @Fd@ @dst@.
1121
1122 <tscreen><verb>
1123 fdClose :: Fd -> IO ()
1124 </verb></tscreen>
1125
1126 @fdClose fd@ calls @close@ to close @Fd@ @fd@.
1127
1128 <tscreen><verb>
1129 fdRead :: Fd -> ByteCount -> IO (String, ByteCount)
1130 </verb></tscreen>
1131
1132 @fdRead fd nbytes@ calls @read@ to read at most @nbytes@
1133 bytes from @Fd@ @fd@, and returns the result as a string
1134 paired with the number of bytes actually read.
1135
1136 The operation may fail with:
1137
1138 <descrip>
1139 <tag>@EOF@</tag>
1140 End of file has been reached.
1141 <tag>@SystemError@</tag>
1142 Various other causes.
1143 </descrip>
1144
1145 <tscreen><verb>
1146 fdWrite :: Fd -> String -> IO ByteCount
1147 </verb></tscreen>
1148
1149 @fdWrite fd s@ calls @write@ to write
1150 the string @s@ to @Fd@ @fd@ as a
1151 contiguous sequence of bytes.  It returns the number of bytes successfully
1152 written.
1153
1154 <tscreen><verb>
1155 queryFdOption :: FdOption -> Fd -> IO Bool
1156 </verb></tscreen>
1157
1158 @getFdOption opt fd@ calls @fcntl@ to determine whether or
1159 not the flag associated with @FdOption@ @opt@ is set for
1160 @Fd@ @fd@.
1161
1162 <tscreen><verb>
1163 setFdOption :: Fd -> FdOption -> Bool -> IO ()
1164 </verb></tscreen>
1165
1166 @setFdOption fd opt val@ calls @fcntl@ to set the flag
1167 associated with @FdOption@ @opt@ on @Fd@ @fd@ to
1168 @val@.
1169
1170 <tscreen><verb>
1171 getLock :: Fd -> FileLock -> IO (Maybe (ProcessID, FileLock))
1172 </verb></tscreen>
1173
1174 @getLock fd lock@ calls @fcntl@ to get the first @FileLock@
1175 for @Fd@ @fd@ which blocks the @FileLock@ @lock@.  If
1176 no such @FileLock@ exists, @getLock@ returns @Nothing@.
1177 Otherwise, it returns @Just (pid, block)@, where @block@ is the
1178 blocking @FileLock@ and @pid@ is the @ProcessID@ of the
1179 process holding the blocking @FileLock@.
1180
1181
1182 <tscreen><verb>
1183 setLock :: Fd -> FileLock -> IO ()
1184 </verb></tscreen>
1185
1186 @setLock fd lock@ calls @fcntl@ with @F_SETLK@ to set or
1187 clear a lock segment for @Fd@ @fd@ as indicated by the
1188 @FileLock@ @lock@.  @setLock@ does not block, but fails with
1189 @SystemError@ if the request cannot be satisfied immediately.
1190
1191 <tscreen><verb>
1192 waitToSetLock :: Fd -> FileLock -> IO ()
1193 </verb></tscreen>
1194
1195 @waitToSetLock fd lock@ calls @fcntl@ with @F_SETLKW@ to set
1196 or clear a lock segment for @Fd@ @fd@ as indicated by the
1197 @FileLock@ @lock@. If the request cannot be satisfied
1198 immediately, @waitToSetLock@ blocks until the request can be
1199 satisfied.
1200
1201
1202 <tscreen><verb>
1203 fdSeek :: Fd -> SeekMode -> FileOffset -> IO FileOffset
1204 </verb></tscreen>
1205
1206 @fdSeek fd whence offset@ calls @lseek@ to position the
1207 @Fd@ @fd@ at the given @offset@ from the starting location
1208 indicated by @whence@.  It returns the resulting offset from the
1209 start of the file in bytes.
1210
1211 <sect2>Posix, Device- and Class-Specific Functions
1212 <label id="Device Specific Functions">
1213 <p>
1214 <nidx>Posix, device and class-specific functions</nidx>
1215
1216 <tscreen><verb>
1217 terminalMode    :: TerminalMode -> TerminalAttributes -> Bool
1218 withMode        :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1219 withoutMode     :: TerminalAttributes -> TerminalMode -> TerminalAttributes
1220
1221 bitsPerByte     :: TerminalAttributes -> Int
1222 withBits        :: TerminalAttributes -> Int -> TerminalAttributes
1223
1224 controlChar     :: TerminalAttributes -> ControlCharacter -> Maybe Char
1225 withCC          :: TerminalAttributes
1226                 -> (ControlCharacter, Char)
1227                 -> TerminalAttributes
1228 withoutCC       :: TerminalAttributes
1229                 -> ControlCharacter
1230                 -> TerminalAttributes
1231
1232 inputTime       :: TerminalAttributes -> Int
1233 withTime        :: TerminalAttributes -> Int -> TerminalAttributes
1234
1235 minInput        :: TerminalAttributes -> Int
1236 withMinInput    :: TerminalAttributes -> Int -> TerminalAttributes
1237
1238 inputSpeed      :: TerminalAttributes -> BaudRate
1239 withInputSpeed  :: TerminalAttributes -> BaudRate -> TerminalAttributes
1240
1241 outputSpeed     :: TerminalAttributes -> BaudRate
1242 withOutputSpeed :: TerminalAttributes -> BaudRate -> TerminalAttributes
1243
1244 getTerminalAttributes :: Fd -> IO TerminalAttributes
1245 </verb></tscreen>
1246
1247 @getTerminalAttributes fd@ calls @tcgetattr@ to obtain
1248 the @TerminalAttributes@ associated with @Fd@ @fd@.
1249
1250 <tscreen><verb>
1251 setTerminalAttributes :: Fd
1252                       -> TerminalAttributes
1253                       -> TerminalState
1254                       -> IO ()
1255 </verb></tscreen>
1256
1257 @setTerminalAttributes fd attr ts@ calls @tcsetattr@ to change
1258 the @TerminalAttributes@ associated with @Fd@ @fd@ to
1259 @attr@, when the terminal is in the state indicated by @ts@.
1260
1261 <tscreen><verb>
1262 sendBreak :: Fd -> Int -> IO ()
1263 </verb></tscreen>
1264
1265 @sendBreak fd duration@ calls @tcsendbreak@ to transmit a
1266 continuous stream of zero-valued bits on @Fd@ @fd@ for the
1267 specified implementation-dependent @duration@.
1268
1269 <tscreen><verb>
1270 drainOutput :: Fd -> IO ()
1271 </verb></tscreen>
1272
1273 @drainOutput fd@ calls @tcdrain@ to block until all output
1274 written to @Fd@ @fd@ has been transmitted.
1275
1276 <tscreen><verb>
1277 discardData :: Fd -> QueueSelector -> IO ()
1278 </verb></tscreen>
1279
1280 @discardData fd queues@ calls @tcflush@ to discard
1281 pending input and/or output for @Fd@ @fd@,
1282 as indicated by the @QueueSelector@ @queues@.
1283
1284 <tscreen><verb>
1285 controlFlow :: Fd -> FlowAction -> IO ()
1286 </verb></tscreen>
1287
1288 @controlFlow fd action@ calls @tcflow@ to control the
1289 flow of data on @Fd@ @fd@, as indicated by
1290 @action@.
1291
1292 <tscreen><verb>
1293 getTerminalProcessGroupID :: Fd -> IO ProcessGroupID
1294 </verb></tscreen>
1295
1296 @getTerminalProcessGroupID fd@ calls @tcgetpgrp@ to
1297 obtain the @ProcessGroupID@ of the foreground process group
1298 associated with the terminal attached to @Fd@ @fd@.
1299
1300 <tscreen><verb>
1301 setTerminalProcessGroupID :: Fd -> ProcessGroupID -> IO ()
1302 </verb></tscreen>
1303
1304 @setTerminalProcessGroupID fd pgid@ calls @tcsetpgrp@ to
1305 set the @ProcessGroupID@ of the foreground process group
1306 associated with the terminal attached to @Fd@
1307 @fd@ to @pgid@.
1308
1309 <sect2>Posix System Databases
1310 <label id="System Database">
1311 <p>
1312 <nidx>Posix, system databases</nidx>
1313
1314 <tscreen><verb>
1315 groupName    :: GroupEntry -> String
1316 groupID      :: GroupEntry -> GroupID
1317 groupMembers :: GroupEntry -> [String]
1318
1319 getGroupEntryForID :: GroupID -> IO GroupEntry
1320 </verb></tscreen>
1321
1322 @getGroupEntryForID gid@ calls @getgrgid@ to obtain
1323 the @GroupEntry@ information associated with @GroupID@
1324 @gid@.
1325
1326 The operation may fail with:
1327
1328 <descrip>
1329 <tag>@NoSuchThing@</tag>
1330 There is no group entry for the GroupID.
1331 </descrip>
1332
1333 <tscreen><verb>
1334 getGroupEntryForName :: String -> IO GroupEntry
1335 </verb></tscreen>
1336
1337 @getGroupEntryForName name@ calls @getgrnam@ to obtain
1338 the @GroupEntry@ information associated with the group called
1339 @name@.
1340
1341 The operation may fail with:
1342
1343 <descrip>
1344 <tag>@NoSuchThing@</tag>
1345 There is no group entry for the name.
1346 </descrip>
1347
1348 <tscreen><verb>
1349 userName      :: UserEntry -> String
1350 userID        :: UserEntry -> UserID
1351 userGroupID   :: UserEntry -> GroupID
1352 homeDirectory :: UserEntry -> String
1353 userShell     :: UserEntry -> String
1354
1355 getUserEntryForID :: UserID -> IO UserEntry
1356 </verb></tscreen>
1357
1358 @getUserEntryForID gid@ calls @getpwuid@ to obtain
1359 the @UserEntry@ information associated with @UserID@
1360 @uid@.
1361 The operation may fail with:
1362
1363 <descrip>
1364 <tag>@NoSuchThing@</tag>
1365 There is no user entry for the UserID.
1366 </descrip>
1367
1368 <tscreen><verb>
1369 getUserEntryForName :: String -> IO UserEntry
1370 </verb></tscreen>
1371
1372 @getUserEntryForName name@ calls @getpwnam@ to obtain
1373 the @UserEntry@ information associated with the user login
1374 @name@.
1375
1376 The operation may fail with:
1377
1378 <descrip>
1379 <tag>@NoSuchThing@</tag>
1380 There is no user entry for the name.
1381 </descrip>
1382
1383 <sect2>POSIX Errors
1384 <label id="Error reporting and handling">
1385 <p>
1386 <nidx>Posix, errors</nidx>
1387
1388 <tscreen><verb>
1389 getErrorCode :: IO ErrorCode
1390 </verb></tscreen>
1391
1392 @getErrorCode@ returns the current value of the external
1393 variable @errno@.  It never fails.
1394
1395 <tscreen><verb>
1396 setErrorCode :: ErrorCode -> IO ()
1397 </verb></tscreen>
1398
1399 @setErrorCode err@ sets the external
1400 variable @errno@ to @err@.  It never fails.
1401
1402 <tscreen><verb>
1403 noError :: ErrorCode
1404 noError = 0
1405
1406 argumentListTooLong, e2BIG              :: ErrorCode
1407 badFd, eBADF                            :: ErrorCode
1408 brokenPipe, ePIPE                       :: ErrorCode
1409 directoryNotEmpty, eNOTEMPTY            :: ErrorCode
1410 execFormatError, eNOEXEC                :: ErrorCode
1411 fileAlreadyExists, eEXIST               :: ErrorCode
1412 fileTooLarge, eFBIG                     :: ErrorCode
1413 filenameTooLong, eNAMETOOLONG           :: ErrorCode
1414 improperLink, eXDEV                     :: ErrorCode
1415 inappropriateIOControlOperation, eNOTTY :: ErrorCode
1416 inputOutputError, eIO                   :: ErrorCode
1417 interruptedOperation, eINTR             :: ErrorCode
1418 invalidArgument, eINVAL                 :: ErrorCode
1419 invalidSeek, eSPIPE                     :: ErrorCode
1420 isADirectory, eISDIR                    :: ErrorCode
1421 noChildProcess, eCHILD                  :: ErrorCode
1422 noLocksAvailable, eNOLCK                :: ErrorCode
1423 noSpaceLeftOnDevice, eNOSPC             :: ErrorCode
1424 noSuchOperationOnDevice, eNODEV         :: ErrorCode
1425 noSuchDeviceOrAddress, eNXIO            :: ErrorCode
1426 noSuchFileOrDirectory, eNOENT           :: ErrorCode
1427 noSuchProcess, eSRCH                    :: ErrorCode
1428 notADirectory, eNOTDIR                  :: ErrorCode
1429 notEnoughMemory, eNOMEM                 :: ErrorCode
1430 operationNotImplemented, eNOSYS         :: ErrorCode
1431 operationNotPermitted, ePERM            :: ErrorCode
1432 permissionDenied, eACCES                :: ErrorCode
1433 readOnlyFileSystem, eROFS               :: ErrorCode
1434 resourceBusy, eBUSY                     :: ErrorCode
1435 resourceDeadlockAvoided, eDEADLK        :: ErrorCode
1436 resourceTemporarilyUnavailable, eAGAIN  :: ErrorCode
1437 tooManyLinks, eMLINK                    :: ErrorCode
1438 tooManyOpenFiles, eMFILE                :: ErrorCode
1439 tooManyOpenFilesInSystem, eNFILE        :: ErrorCode
1440
1441 </verb></tscreen>