Return to intro.2 CVS log

Up to [Research Unix] / researchv10dc / man / adm / man2

Annotation of researchv10dc/man/adm/man2/intro.2, revision 1.1

1.1     ! root        1: .TH INTRO 2
        !             2: .de en
        !             3: .HP
        !             4: \\$1  \fL\\$2\fP  \\$3
        !             5: .br
        !             6: ..
        !             7: .SH NAME
        !             8: intro, errno \(mi introduction to system calls and error numbers
        !             9: .SH SYNOPSIS
        !            10: .B #include <errno.h>
        !            11: .SH DESCRIPTION
        !            12: Section 2 describes the entries into the operating system.
        !            13: .SS "File I/O"
        !            14: Files are opened for input or output
        !            15: by
        !            16: .IR open (2)
        !            17: or
        !            18: .IR creat .
        !            19: These calls return a integer called a
        !            20: .IR "file descriptor"
        !            21: which identifies the file
        !            22: to subsequent I/O calls,
        !            23: notably
        !            24: .IR read (2)
        !            25: and
        !            26: .IR write .
        !            27: File descriptors range from 0 to 127 in the current system.
        !            28: The system gets to pick the numbers,
        !            29: but they may be reassigned by
        !            30: .IR dup (2)
        !            31: and
        !            32: .IR dup2 .
        !            33: .PP
        !            34: By agreement among user programs,
        !            35: file descriptor 0 is the standard input,
        !            36: 1 is the standard output,
        !            37: 2 is for error messages,
        !            38: and 3 is the controlling terminal if any.
        !            39: The operating system is unaware of these conventions;
        !            40: it is permissible to close file 0,
        !            41: or even to replace it by a file open only for writing,
        !            42: but many programs will be confused by such chicanery.
        !            43: .PP
        !            44: Files are normally read or written in sequential order.
        !            45: .IR Lseek (2)
        !            46: addresses arbitrary locations.
        !            47: .PP
        !            48: Files have associated status,
        !            49: consisting of ownerships,
        !            50: permission modes,
        !            51: access dates,
        !            52: and so on.
        !            53: The status is retrieved by
        !            54: .IR stat (2);
        !            55: the calls in
        !            56: .IR chmod (2)
        !            57: alter parts of it.
        !            58: .PP
        !            59: New files are made with
        !            60: .I creat
        !            61: (in
        !            62: .IR open (2)).
        !            63: An existing file may be given an additional name
        !            64: by
        !            65: .IR link (2)
        !            66: or
        !            67: .IR symlink ;
        !            68: names are removed by
        !            69: .IR unlink (2).
        !            70: Directories are created and removed by
        !            71: .IR mkdir (2)
        !            72: and
        !            73: .IR rmdir .
        !            74: .PP
        !            75: Device files and communication channels
        !            76: (streams)
        !            77: admit a plethora of special operations,
        !            78: most specific to the device in question;
        !            79: see
        !            80: .IR ioctl (2)
        !            81: and the device writeups in section 4,
        !            82: especially
        !            83: .IR ttyld (4)
        !            84: for terminals
        !            85: and
        !            86: .IR stream (4)
        !            87: for communications.
        !            88: .IR Pipe (2)
        !            89: creates a nameless stream,
        !            90: useful for local communication.
        !            91: Several streams may be monitored in parallel by
        !            92: .IR select (2).
        !            93: .SS "Process execution and control"
        !            94: A new process is created
        !            95: when an existing one calls
        !            96: .IR fork (2).
        !            97: The new (child) process starts out with
        !            98: copies of the address space and most other attributes
        !            99: of the old (parent) process.
        !           100: In particular,
        !           101: the child starts out running
        !           102: the same program as the parent;
        !           103: .IR exec (2)
        !           104: will bring in a different one.
        !           105: .PP
        !           106: Each process has an integer process id,
        !           107: unique among all currently active processes;
        !           108: a process group id,
        !           109: used to distribute signals
        !           110: among processes in the same session
        !           111: or window;
        !           112: a userid and groupid,
        !           113: which determine access permissions;
        !           114: and
        !           115: a character-string login name
        !           116: for the current user
        !           117: (not the same as permissions).
        !           118: The calls in
        !           119: .IR getuid (2)
        !           120: retrieve and change these values.
        !           121: .PP
        !           122: Various events cause software traps (signals):
        !           123: program errors like addressing violations,
        !           124: software events like the interrupt key on the terminal,
        !           125: the alarm clock set by
        !           126: .IR alarm (2),
        !           127: calls to
        !           128: .IR kill
        !           129: (in
        !           130: .IR signal (2)).
        !           131: Most signals terminate the process by default;
        !           132: .IR signal (2)
        !           133: will arrange to trap or ignore them instead.
        !           134: .PP
        !           135: A process terminates
        !           136: on receiving a signal
        !           137: or by calling
        !           138: .IR exit (2).
        !           139: A parent process may call
        !           140: .I wait
        !           141: (in
        !           142: .IR exit (2))
        !           143: to wait for some child to terminate.
        !           144: A single byte of status information
        !           145: may be passed from
        !           146: .I exit
        !           147: to
        !           148: .IR wait .
        !           149: .SS "Timekeeping"
        !           150: .IR Time (2)
        !           151: and
        !           152: .I ftime
        !           153: return the time of day
        !           154: and related information.
        !           155: .IR Times (2)
        !           156: returns runtime accounting
        !           157: for this process
        !           158: and its children.
        !           159: .IR Profil
        !           160: arranges to increment various locations
        !           161: in memory whenever the clock ticks;
        !           162: it is useful for execution profiling.
        !           163: .PP
        !           164: .IR Times ,
        !           165: .IR profil ,
        !           166: and a few other calls
        !           167: measure time in clock ticks.
        !           168: The clock frequency is given by the constant
        !           169: .B HZ
        !           170: in
        !           171: .BR <sys/param.h> ;
        !           172: 60 ticks per second
        !           173: in this system.
        !           174: .SH SEE ALSO
        !           175: .IR intro (3),
        !           176: .IR perror (3)
        !           177: .SH DIAGNOSTICS
        !           178: A `Diagnostics' paragraph appears in the page for each system call
        !           179: that has an error return.
        !           180: Unless otherwise stated, the error value is the integer \-1,
        !           181: and the success value is 0.
        !           182: When an error occurs,
        !           183: an error number is assigned to
        !           184: the external variable
        !           185: .IR errno .
        !           186: .I Errno
        !           187: is not cleared on successful calls, so it should be tested only
        !           188: after an error has occurred.
        !           189: .PP
        !           190: There is a table of messages that describe the errors
        !           191: and a routine for printing them;
        !           192: see
        !           193: .IR perror (3).
        !           194: The list below gives
        !           195: the number, the name (as defined in
        !           196: .BR <errno.h> ),
        !           197: and the
        !           198: .I perror
        !           199: message for each error type.
        !           200: The reasons for error returns are explained in general terms;
        !           201: further explanations for less obvious error returns
        !           202: appear in the writeups of individual system calls.
        !           203: .en 0 \h'\w'EIO'u' "Error 0
        !           204: No error has occurred.
        !           205: .en 1 EPERM "Not owner
        !           206: An attempt was made to modify a file in some way forbidden
        !           207: except to its owner or the super-user,
        !           208: or an ordinary user attempted to do something
        !           209: allowed only to the super-user.
        !           210: .en 2 ENOENT "No such file or directory
        !           211: A file name was specified
        !           212: and the file should exist but didn't, or one
        !           213: of the directories in a path name did not exist.
        !           214: .en 3 ESRCH "No such process
        !           215: The process whose number was given to
        !           216: .I kill
        !           217: did not exist, or was already dead.
        !           218: .en 4 EINTR "Interrupted system call
        !           219: A signal
        !           220: which the user has elected to catch
        !           221: occurred during a system call.
        !           222: If execution is resumed
        !           223: after processing the signal,
        !           224: it will appear as if the interrupted system call
        !           225: returned this error condition.
        !           226: .en 5 EIO "I/O error
        !           227: A physical I/O error
        !           228: or timeout occurred,
        !           229: usually in
        !           230: .IR read ,
        !           231: .IR write ,
        !           232: or
        !           233: .IR ioctl .
        !           234: This error may in some cases be returned
        !           235: on a call following the one to which it actually applies.
        !           236: .en 6 ENXIO "No such device or address
        !           237: I/O on a special file referred to a device which does not
        !           238: exist or is off line,
        !           239: or beyond the limits of the device.
        !           240: .en 7 E2BIG "Arg list too long
        !           241: An argument list longer than 16384 bytes
        !           242: was presented to
        !           243: .IR exec .
        !           244: .en 8 ENOEXEC "Exec format error
        !           245: A request was made to execute a file
        !           246: which, although it had the appropriate permissions,
        !           247: did not start with a valid magic number, see
        !           248: .IR a.out (5).
        !           249: .en 9 EBADF "Bad file number
        !           250: A file descriptor referred to no
        !           251: open file,
        !           252: or a
        !           253: .I read
        !           254: (resp.
        !           255: /IR write )
        !           256: a file which was open only for writing (resp. reading).
        !           257: .en 10 ECHILD "No children
        !           258: In
        !           259: .IR wait ,
        !           260: the process had no
        !           261: living or unwaited-for children.
        !           262: .en 11 EAGAIN "No more processes
        !           263: In
        !           264: .IR fork ,
        !           265: the system's process table was full
        !           266: or the user was not allowed to create any more
        !           267: processes.
        !           268: .en 12 ENOMEM "Not enough memory
        !           269: During
        !           270: .I exec
        !           271: or
        !           272: .I brk,
        !           273: a program asked for more memory or swap space
        !           274: than the system was able to supply.
        !           275: .en 13 EACCES "Permission denied
        !           276: An attempt was made to access a file in a way forbidden
        !           277: by the protection system.
        !           278: .en 14 EFAULT "Bad address
        !           279: The system encountered a hardware fault in attempting to
        !           280: access the arguments of a system call.
        !           281: .en 15 EHASF "Directory not empty
        !           282: An attempt was made to remove a nonempty directory.
        !           283: .en 16 EBUSY "In use
        !           284: An attempt was made to mount a device that was already mounted
        !           285: (or crashed or was copied in mounted state),
        !           286: to dismount a device
        !           287: on which there was an active file
        !           288: (open file, current directory, mounted-on file, active text segment),
        !           289: or to remove the current directory of some process.
        !           290: .en 17 EEXIST "File exists
        !           291: An existing file was mentioned in an inappropriate context,
        !           292: e.g.
        !           293: .IR link .
        !           294: .en 18 EXDEV "Cross-device link
        !           295: A link to a file on another device
        !           296: was attempted.
        !           297: .en 19 ENODEV "No such device
        !           298: An attempt was made to apply an inappropriate
        !           299: system call to a device;
        !           300: e.g. read a write-only device.
        !           301: .en 20 ENOTDIR "Not a directory
        !           302: A non-directory was specified where a directory
        !           303: is required,
        !           304: for example in a path name or
        !           305: as an argument to
        !           306: .IR chdir .
        !           307: .en 21 EISDIR "Is a directory
        !           308: An attempt to write on a directory.
        !           309: .en 22 EINVAL "Invalid argument
        !           310: Some invalid argument:
        !           311: dismounting a non-mounted
        !           312: device,
        !           313: mentioning an unknown signal in
        !           314: .IR signal ,
        !           315: reading or writing a file for which
        !           316: .I lseek
        !           317: has generated a negative pointer.
        !           318: Also set by math functions, see
        !           319: .IR intro (3).
        !           320: .en 23 ENFILE "File table overflow
        !           321: The system's table of open files was full,
        !           322: and temporarily no more
        !           323: .I opens
        !           324: could be accepted.
        !           325: .en 24 EMFILE "Too many open files
        !           326: The limit is 128 per process.
        !           327: .en 25 ENOTTY "Illegal ioctl
        !           328: The function code mentioned in
        !           329: .I ioctl
        !           330: does not apply to the file or device.
        !           331: .en 26 ETXTBSY "Text file busy
        !           332: An attempt to execute a pure-procedure
        !           333: program which was open for writing,
        !           334: or to open for writing a pure-procedure
        !           335: program that was being executed.
        !           336: .en 27 EFBIG "File too large
        !           337: The size of a file exceeded the maximum (about
        !           338: .if t 10\u\s-29\s+2\d
        !           339: .if n 1.0E9
        !           340: bytes).
        !           341: .en 28 ENOSPC "No space left on device
        !           342: During a
        !           343: .I write
        !           344: to an ordinary file,
        !           345: there was no free space left on the device.
        !           346: .en 29 ESPIPE "Illegal seek
        !           347: .I Lseek
        !           348: was issued to a stream device.
        !           349: .en 30 EROFS "Read-only file system
        !           350: An attempt to modify a file or directory
        !           351: was made
        !           352: on a device mounted read-only.
        !           353: .en 31 EMLINK "Too many links
        !           354: An attempt to make more than 32767 links to a file.
        !           355: .en 32 EPIPE "Broken pipe
        !           356: .I Write
        !           357: to a stream that has been hung up,
        !           358: usually a pipe with no process to read the data.
        !           359: This condition normally generates a signal;
        !           360: the error is returned if the signal is ignored.
        !           361: .en 33 EDOM "Math argument
        !           362: The argument of a function in the math package (3M)
        !           363: was out of the domain of the function.
        !           364: .en 34 ERANGE "Result too large
        !           365: The value of a function in the math package (3M)
        !           366: was unrepresentable within machine precision.
        !           367: .en 35 ELOOP "Link loop
        !           368: An endless cycle of symbolic links was encountered.
        !           369: .en 36 ECONC "Concurrency violation
        !           370: An
        !           371: .I open
        !           372: or
        !           373: .I creat
        !           374: was in violation of the concurrent access specified
        !           375: for the file.
        !           376: .en 37 EGREG "It's all Greg's fault
        !           377: Something went wrong.
        !           378: .SH BUGS
        !           379: Device and file system drivers
        !           380: may use error codes in
        !           381: unexpected or unconventional ways;
        !           382: it is infeasible to list them all.
        !           383: The writeups in section 4
        !           384: list some such special cases.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.