intro(2)



NAME

     intro, errno - introduction to system calls and error numbers


SYNOPSIS

     #include <errno.h>


DESCRIPTION

     This section describes all of the system calls.  Most of these calls have
     one  or  more  error  returns.   An  error  condition  is indicated by an
     otherwise impossible  return  value.   This  is  almost  always  -1;  the
     individual  descriptions  specify  the  details.   Note  that a number of
     system calls overload the meanings of these error numbers, and  that  the
     meanings  must  be interpreted according to the type and circumstances of
     the call.

     As with normal arguments, all return codes and values from functions  are
     of  type  integer  unless  otherwise noted.  An error number is also made
     available in the  external  variable  errno,  which  is  not  cleared  on
     successful  calls.   Thus  errno should be tested only after an error has
     occurred.

     The following is a complete list of the errors and their names  as  given
     in <sys/errno.h>:

0  OK  Error 0
     Unused.  (The symbol "OK" is only used inside the kernel source.)

1  EPERM  Not owner
     Typically this error indicates an attempt to modify a file  in  some  way
     forbidden  except  to  its  owner or super-user.  It is also returned for
     attempts by ordinary users to do things allowed only to the super-user.

2  ENOENT  No such file or directory
     This error occurs when a file name is specified and the file should exist
     but  doesn't,  or  when  one  of  the directories in a path name does not
     exist.

3  ESRCH  No such process
     The process or process group whose number was given does  not  exist,  or
     any such process is already dead.

4  EINTR  Interrupted system call
     An asynchronous signal (such as interrupt or  quit)  that  the  user  has
     elected  to catch occurred during a system call.  If execution is resumed
     after processing the signal and the system call is not restarted, it will
     appear as if the interrupted system call returned this error condition.

5  EIO  I/O error
     Some physical I/O error occurred during an I/O operation, usually read or
     write.   Operations  on  file  descriptors that refer to devices that are
     forcefully taken away or in a bad state will also provoke this error.

6  ENXIO  No such device or address
     I/O on a special file refers to a  subdevice  that  does  not  exist,  or
     beyond the limits of the device.  It may also occur when, for example, an
     illegal tape drive unit number is selected or a disk pack is  not  loaded
     on a drive.

7  E2BIG  Arg list too long
     An argument list longer  than  ARG_MAX  bytes  is  presented  to  execve.
     ARG_MAX  is  set  to  4096 bytes for 16-bit Minix, 16384 bytes for 32-bit
     Minix, and unlimited for Minix-vmd as these systems are released.

8  ENOEXEC  Exec format error
     A request is made to execute a file that, although it has the appropriate
     permissions, does not start with a valid magic number, (see a.out(5)).

9  EBADF  Bad file number
     Either a file descriptor refers to no open file, or a read (resp.  write)
     request is made to a file that is open only for writing (resp. reading).

10  ECHILD  No children
     Wait and the process has no living or unwaited-for children.

11  EAGAIN  Resource temporarily unavailable
     In a fork, the system's process table is full or the user is not  allowed
     to  create  any more processes, otherwise an operation that would cause a
     process to block was attempted on an object  in  non-blocking  mode  (see
     fcntl(2)).

12  ENOMEM  Not enough core
     During an execve or brk, a program asks for more  (virtual)  memory  than
     the  system is able to supply, or a process size limit would be exceeded.
     The maximum size of  the  data+stack  segment  is  set  by  the  chmem(1)
     program.   For  Minix-vmd  a  small  data+stack  size  is  increased to 3
     megabytes when a program is executed.

13  EACCES  Permission denied
     An attempt was made to access a file in a way forbidden by the protection
     system.   Also an attempt to open a device for writing that is physically
     write protected.

14  EFAULT  Bad address
     An argument of a system call is outside the address space allocated to  a
     process.

15  ENOTBLK  Block device required
     A plain file was mentioned where a block device was  required,  e.g.,  in
     mount.

16  EBUSY  Resource busy
     An attempt to mount a device that was already mounted or an  attempt  was
     made  to  dismount  a device on which there is an active file (open file,
     current directory, mounted-on file, or active text segment).   A  request
     was made to an exclusive access device that was already in use.

17  EEXIST  File exists
     An existing file was mentioned in an inappropriate context, e.g., link.

18  EXDEV  Cross-device link
     A hard link to a file on another device was attempted.

19  ENODEV  No such device
     An attempt was made to access a device that  is  not  configured  by  the
     system, i.e., there is no driver for the device.

20  ENOTDIR  Not a directory
     A non-directory was specified where a directory is required, for example,
     in a path name or as an argument to chdir.

21  EISDIR  Is a directory
     An attempt to write on a directory.

22  EINVAL  Invalid argument
     Some invalid argument:  dismounting a non-mounted device,  mentioning  an
     unknown  signal  in  signal, or some other argument inappropriate for the
     call.  Also set by math functions, (see math(3)).

23  ENFILE  File table overflow
     The system's table of open files is full, and temporarily no  more  opens
     can be accepted.

24  EMFILE  Too many open files
     The limit on the number of open files per process, OPEN_MAX, is  reached.
     As released, this limit is 20 for Minix, and 30 for Minix-vmd.

25  ENOTTY  Not a typewriter
     The file mentioned in an ioctl is not a terminal or one of the devices to
     which  this  call  applies.  (Often seen error from programs with bugs in
     their error reporting code.)

26  ETXTBSY  Text file busy
     Attempt to execute a program that is open for  writing.   Obsolete  under
     Minix.

27  EFBIG  File too large
     The size of a file exceeded the maximum (little over 64 megabytes for the
     V2 file system).


28  ENOSPC  No space left on device
     A write to an ordinary file, the creation  of  a  directory  or  symbolic
     link,  or  the  creation of a directory entry failed because no more disk
     blocks are available on the file system, or the allocation  of  an  inode
     for  a  newly created file failed because no more inodes are available on
     the file system.

29  ESPIPE  Illegal seek
     An lseek was issued to a pipe or TCP/IP channel.  This error may also  be
     issued for other non-seekable devices.

30  EROFS  Read-only file system
     An attempt to modify a file or directory was made  on  a  device  mounted
     read-only.

31  EMLINK  Too many links
     An attempt to make more than a certain number of hard links  to  a  file.
     The  advertized  maximum,  LINK_MAX,  is  127,  but Minix-vmd uses a much
     larger maximum of 32767 for the V2 file system.

32  EPIPE  Broken pipe
     A write on a pipe or TCP/IP channel for which there is no process to read
     the  data.   This  condition  normally  generates the signal SIGPIPE; the
     error is returned if the signal is caught or ignored.

33  EDOM  Math argument
     The argument of a function in the math package is out of  the  domain  of
     the function.

34  ERANGE  Result too large
     The value of a function in the math  package  is  unrepresentable  within
     machine precision.

35  EDEADLK  Resource deadlock avoided
     A process attempts to place a blocking lock on a  file  that  is  already
     locked  by  another  process  and  that  process is waiting for the first
     process to unlock a file that first process already has a lock on.   (The
     classic  "lock  A,  lock B" by process 1, and "lock B, lock A" by process
     2.)

36  ENAMETOOLONG  File name too long
     The path name  exceeds  PATH_MAX  characters.   PATH_MAX  equals  255  as
     distributed.

37  ENOLCK  No locks available
     The system's table of active locks is full.

38  ENOSYS  Function not implemented
     The system call is not supported.  Either an old program uses an obsolete
     call,  or  a  program  for a more capable system is run on a less capable
     system.

39  ENOTEMPTY  Directory not empty
     A directory with entries other than "." and ".." was supplied to a remove
     directory or rename call.

40  ELOOP  Too many symbolic links
     A path name lookup involved more than SYMLOOP  symbolic  links.   SYMLOOP
     equals 8 as distributed.  (Minix-vmd)

50  EPACKSIZE  Invalid packet size

51  EOUTOFBUFS  Not enough buffers left

52  EBADIOCTL  Illegal ioctl for device

53  EBADMODE  Bad mode in ioctl

54  EWOULDBLOCK  Would block

55  EBADDEST  Bad destination address

56  EDSTNOTRCH  Destination not reachable

57  EISCONN  Already connected

58  EADDRINUSE  Address in use

59  ECONNREFUSED  Connection refused

60  ECONNRESET  Connection reset

61  ETIMEDOUT  Connection timed out

62  EURG  Urgent data present

63  ENOURG  No urgent data present

64  ENOTCONN  No connection

65  ESHUTDOWN  Already shutdown

66  ENOCONN  No such connection

67  EINPROGRESS  Operation now in progress

68  EALREADY  Operation already in progress




DEFINITIONS


     Process ID
          Each active process in  the  system  is  uniquely  identified  by  a
          positive  integer called a process ID.  The range of this ID is from
          1 to 29999.  The special process with process  ID  1  is  init,  the
          ancestor of all processes.

     Parent process ID
          A new process  is  created  by  a  currently  active  process;  (see
          fork(2)).   The  parent process ID of a process is the process ID of
          its creator, unless the creator dies, then init becomes  the  parent
          of the orphaned process.

     Process Group ID
          Each active  process  is  a  member  of  a  process  group  that  is
          identified  by a positive integer called the process group ID.  This
          is the process ID of the group leader.  This  grouping  permits  the
          signaling of related processes (see kill(2)).

     Real User ID and Real Group ID
          Each user on the system is identified by a positive  integer  termed
          the real user ID.

          Each user is also a member of one or  more  groups.   One  of  these
          groups  is  distinguished  from  others  and  used  in  implementing
          accounting facilities.  The positive integer corresponding  to  this
          distinguished  group  is  termed the real group ID.  (Under standard
          Minix this is the only group a process can be a member of.)

          All processes have a real user ID and  real  group  ID.   These  are
          initialized  from  the  equivalent  attributes  of  the process that
          created it.

     Effective User Id, Effective Group Id, and Access Groups
          Access to  system  resources  is  governed  by  three  values:   the
          effective  user  ID,  the  effective  group ID, and the group access
          list.

          The effective user ID and  effective  group  ID  are  initially  the
          process's  real  user ID and real group ID respectively.  Either may
          be modified through execution of a set-user-ID or set-group-ID  file
          (possibly by one its ancestors) (see execve(2)).

          The group access list is an additional set of group ID's  used  only
          in  determining resource accessibility.  Access checks are performed
          as described below in  ``File  Access  Permissions''.   The  maximum
          number  of  additional group ID's is NGROUPS_MAX.  For Minix this is
          0, but Minix-vmd supports a list of up to 16 additional group  ID's.
          (Also known as ``supplemental'' group ID's.)

     Super-user
          A process is recognized as  a  super-user  process  and  is  granted
          special privileges if its effective user ID is 0.

     Descriptor
          An integer  assigned  by  the  system  when  a  file  or  device  is
          referenced  by open(2), dup(2) or fcntl(2) which uniquely identifies
          an access path to that file or device from a given process or any of
          its children.

     File Descriptor
          Older, and often used name for a descriptor.

     File Name
          Names consisting of up to NAME_MAX characters may be used to name an
          ordinary  file, special file, or directory.  NAME_MAX is the maximum
          of the maximum file name lengths  of  the  supported  file  systems.
          Excess  characters are ignored when too long file names are used for
          files in a given file system.  The maximum file name length  of  the
          V1  and  V2  file  systems  is  14 characters.  The Minix-vmd "flex"
          variants of V1 and V2 have a 60 character maximum.

          The characters in a file name may assume any value representable  in
          eight bits excluding 0 (null) and the ASCII code for / (slash).

          Note that it is generally unwise to use one  of  \'"<>();~$^&*|{}[]?
          as  part  of  file  names because of the special meaning attached to
          these characters by the shell.

     Path Name
          A path name is a null-terminated character string starting  with  an
          optional  slash  (/),  followed  by  zero  or  more  directory names
          separated by slashes, optionally followed by a file name.  The total
          length  of a path name must be less than PATH_MAX characters (255 as
          distributed.)

          If a path name begins with a slash, the path search  begins  at  the
          root  directory.   Otherwise,  the  search  begins  from the current
          working directory.  A slash by itself names the root  directory.   A
          null  pathname  is  illegal, use "." to refer to the current working
          directory.

     Directory
          A directory is a special type of file that contains entries that are
          references  to other files.  Directory entries are called links.  By
          convention, a directory contains at  least  two  links,  .  and  ..,
          referred  to  as  dot  and  dot-dot respectively.  Dot refers to the
          directory itself and dot-dot refers to its parent directory.


     Root Directory and Current Working Directory
          Each process has associated with it a concept of  a  root  directory
          and  a  current  working directory for the purpose of resolving path
          name searches.  A process's root directory  need  not  be  the  root
          directory of the root file system.

     File Access Permissions
          Every file in the file system  has  a  set  of  access  permissions.
          These  permissions  are  used  in  determining whether a process may
          perform a requested operation on the file (such as  opening  a  file
          for writing).  Access permissions are established at the time a file
          is created.  They may be changed at  some  later  time  through  the
          chmod(2) call.

          File access is broken down according to whether a file may be: read,
          written, or executed.  Directory files use the execute permission to
          control if the directory may be searched.

          File access permissions are interpreted by the system as they  apply
          to  three  different  classes of users: the owner of the file, those
          users  in  the  file's  group,  anyone  else.   Every  file  has  an
          independent  set  of  access  permissions for each of these classes.
          When an access check is  made,  the  system  decides  if  permission
          should  be  granted by checking the access information applicable to
          the caller.

          Read, write, and execute/search permissions on a file are granted to
          a process if:

          The process's effective user ID is that of the super-user.

          The process's effective user ID matches the user ID of the owner  of
          the file and the owner permissions allow the access.

          The process's effective user ID does not match the user  ID  of  the
          owner  of  the  file,  and  either  the process's effective group ID
          matches the group ID of the file, or the group ID of the file is  in
          the process's group access list, and the group permissions allow the
          access.

          Neither the effective user ID  nor  effective  group  ID  and  group
          access list of the process match the corresponding user ID and group
          ID of the file,  but  the  permissions  for  ``other  users''  allow
          access.

          Otherwise, permission is denied.





SEE ALSO

     intro(3), strerror(3).