INTRO(2)                         System Calls                         INTRO(2)




NAME

       intro - introduction to system calls and error numbers


SYNOPSIS

       #include <sys/errno.h>


DESCRIPTION

       This  section provides an overview of the GNO system calls, their error
       returns, and other common definitions  and  concepts.   Some  functions
       listed  in  this  chapter are not actually implemented as kernel traps,
       but have been listed as such because they would be system  calls  on  a
       traditional Unix system.

       The  SYNOPSIS  section  of each manual page gives the prototype for the
       function(s) described, along with a listing of the header  files  which
       provide  the  prototypes.  The sequence of header file inclusion may be
       important, so they should be included in the sequence given.

       The DESCRIPTION section gives the detailed description  of  the  system
       call.

       Reference  may be made to symbolic links or other features or functions
       that are either unimplemented or otherwise unavailable under GNO.  This
       information has often been obtained from the original BSD manual pages.
       In most cases such information has been  retained  in  the  GNO  manual
       pages  either  because  such  functionality  is  planned or because the
       information is relevent to code intended to run on other BSD  operating
       systems.


DIAGNOSTICS

       Nearly  all of the system calls provide an error number in the external
       variable errno, which is defined as:

              extern int errno;

       When a system call detects an error, it returns an integer value  indi-
       cating  failure  (usually  -1) and sets the variable errno accordingly.
       (This allows interpretation of the failure on receiving  a  -1  and  to
       take  action accordingly.)  Successful calls never set errno; once set,
       it remains until another error occurs.   It  should  only  be  examined
       after  an error.  Note that a number of system calls overload the mean-
       ings of these error numbers, and that the meanings must be  interpreted
       according to the type and circumstances of the call.

       The  following  is  a complete list of the errors used in GNO and their
       names as given in <sys/errno.h>.  The first twelve (up to  ENOSPC)  are
       also used by the ORCA/Shell.

              ENOERR -- Error 0
                     Not used.

              EDOM -- Numerical argument out of domain
                     A numerical input argument was outside the defined domain
                     of the mathematical function.

              ERANGE -- Numerical result out of range
                     A numerical result of the function was too large  to  fit
                     in the available space (perhaps exceeded precision).

              ENOMEM -- Cannot allocate memory
                     The  new  process  image  required  more  memory than was
                     allowed by  the  hardware  or  by  system-imposed  memory
                     management constraints.

              ENOENT -- No such file or directory
                     A component of a specified pathname did not exist, or the
                     pathname was an empty string.

              EIO -- Input/output error
                     Some physical input or output error occurred.

                     Any GS/OS errors that occur and which  do  not  have  any
                     other  suitable errno counterparts will be mapped to this
                     error.

              EINVAL -- Invalid argument
                     Some invalid argument was supplied. (For example,  speci-
                     fying  an undefined signal to a signal or kill function).

              EBADF -- Bad file descriptor
                     A file descriptor argument was out of range, referred  to
                     no  open  file,  or  a read (write) request was made to a
                     file that was only open for writing (reading).

              EMFILE -- Too many open files
                     (The limit on the number of open files per process is 32.
                     This is configurable under some versions of Unix, but not
                     under GNO.)  Getdtablesize(2)  will  obtain  the  current
                     limit.

              EACCES -- Permission denied
                     An  attempt  was made to access a file in a way forbidden
                     by its file access permissions.

                     The default ORCA/C header files  use  EACCESS  (with  two
                     S?s)  for  this macro, but GNO does not since it causes a
                     conflict  with  standard  macros  in  the   <arpa/tftp.h>
                     header.

              EEXIST -- File exists
                     An  existing  file was mentioned in an inappropriate con-
                     text.

              ENOSPC -- Device out of space
                     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 were available on  the
                     file  system, or (for filesystems using inodes) the allo-
                     cation of an  inode  for  a  newly  created  file  failed
                     because no more inodes were available on the file system.

              EPERM -- Operation not permitted
                     An attempt was made to perform an  operation  limited  to
                     processes  with appropriate privileges or to the owner of
                     a file or other resources.

              ESRCH -- No such process
                     No process could be found corresponding to that specified
                     by the given process ID.

              EINTR -- Interrupted function call
                     An  asynchronous  signal  (such as SIGINT or SIGQUIT) was
                     caught by the process during the execution of  an  inter-
                     ruptible  function. If the signal handler performs a nor-
                     mal return, the interrupted function call  will  seem  to
                     have returned the error condition.

              E2BIG -- Arg list too long
                     The number of bytes used for the argument and environment
                     list of the new process exceeded  the  current  limit  of
                     4096 bytes (NCARGS in <sys/param.h>).

              ENOEXEC -- Exec format error
                     A  request  was  made to execute a file that, although it
                     has the appropriate permissions, was not  in  the  format
                     required for an executable file.

              ECHILD -- No child processes
                     A wait or waitpid function was executed by a process that
                     had no existing or unwaited-for child processes.

              EAGAIN -- Resource temporarily unavailable
                     This is a temporary condition and later calls to the same
                     routine may complete normally.

              ENOTDIR -- Not a directory
                     A component of the specified pathname existed, but it was
                     not a directory, when a directory was expected.

              ENOTTY -- Inappropriate ioctl for device
                     A control function (see ioctl(2))  was  attempted  for  a
                     file  or special device for which the operation was inap-
                     propriate.

              EPIPE -- Broken pipe
                     A write on a pipe, socket or FIFO for which there  is  no
                     process to read the data.

              ESPIPE -- Illegal seek
                     An lseek function was issued on a socket, pipe or FIFO.

              ENOTBLK -- Not a block device
                     A  block  device  operation  was attempted on a non-block
                     device or file.

              EISDIR -- Is a directory
                     An attempt was made to open a directory with  write  mode
                     specified.

              ENOTSOCK -- Socket operation on non-socket
                     Self-explanatory.

              EDESTADDRREQ -- Destination address required
                     A  required  address  was  omitted from an operation on a
                     socket.

              EMSGSIZE -- Message too long
                     A message sent on a socket was larger than  the  internal
                     message buffer or some other network limit.

              EPROTOTYPE -- Protocol wrong type for socket
                     A protocol was specified that does not support the seman-
                     tics of the socket type requested. For example, you  can-
                     not   use  the  ARPA  Internet  UDP  protocol  with  type
                     SOCK_STREAM.

              ENOPROTOOPT -- Protocol not available
                     A bad option or level was specified in a getsockopt(2) or
                     setsockopt(2) call.

              EPROTONOSUPPORT -- Protocol not supported
                     The  protocol  has not been configured into the system or
                     no implementation for it exists.

              ESOCKTNOSUPPORT -- Socket type not supported
                     The support for the socket type has not  been  configured
                     into the system or no implementation for it exists.

              EOPNOTSUPP -- Operation not supported
                     The  attempted operation is not supported for the type of
                     object referenced.   Usually  this  occurs  when  a  file
                     descriptor refers to a file or socket that cannot support
                     this operation, for example, trying to accept  a  connec-
                     tion on a datagram socket.

              EPFNOSUPPORT -- Protocol family not supported
                     The protocol family has not been configured into the sys-
                     tem or no implementation for it exists.

              EAFNOSUPPORT -- Address family not supported by protocol family
                     An address incompatible with the requested  protocol  was
                     used.   For  example, you shouldn't necessarily expect to
                     be able to use NS addresses with ARPA Internet protocols.

              EADDRINUSE -- Address already in use
                     Only one usage of each address is normally permitted.

              EADDRNOTAVAIL -- Cannot assign requested address
                     Normally  results from an attempt to create a socket with
                     an address not on this machine.

              ENETDOWN -- Network is down
                     A socket operation encountered a dead network.

              ENETUNREACH -- Network is unreachable
                     A socket operation was attempted to an  unreachable  net-
                     work.

              ENETRESET -- Network dropped connection on reset
                     The host you were connected to crashed and rebooted.

              ECONNABORTED -- Software caused connection abort
                     A  connection  abort  was  caused  internal  to your host
                     machine.

              ECONNRESET -- Connection reset by peer
                     A connection was forcibly closed by a  peer.   This  nor-
                     mally results from a loss of the connection on the remote
                     socket due to a timeout or a reboot.

              ENOBUFS -- No buffer space available
                     An operation on  a  socket  or  pipe  was  not  performed
                     because  the  system  lacked  sufficient  buffer space or
                     because a queue was full.

              EISCONN -- Socket is already connected
                     A connect  request  was  made  on  an  already  connected
                     socket;  or,  a  sendto or sendmsg request on a connected
                     socket specified a destination when already connected.

              ENOTCONN -- Socket is not connected
                     An request to send or receive data was disallowed because
                     the socket was not connected and (when sending on a data-
                     gram socket) no address was supplied.

              ESHUTDOWN -- Cannot send after socket shutdown
                     A request to send data was disallowed because the  socket
                     had  already  been  shut down with a previous shutdown(2)
                     call.

              ETIMEDOUT -- Operation timed out
                     A connect or send request failed  because  the  connected
                     party  did  not  properly respond after a period of time.
                     (The timeout period is  dependent  on  the  communication
                     protocol.)

              ECONNREFUSED -- Connection refused
                     No  connection  could  be made because the target machine
                     actively refused it.  This usually results from trying to
                     connect  to  a  service  that  is inactive on the foreign
                     host.

              EWOULDBLOCK -- Operation would block
                     An  operation  was  attempted  on  a  non-blocking   file
                     descriptor that would cause the calling process to block.

              EINPROGRESS -- Operation now in progress
                     An operation that takes a long time to complete (such  as
                     a connect(2)) was attempted on a non-blocking object (see
                     fcntl(2)).

              EALREADY -- Operation already in progress
                     An operation was attempted on a non-blocking object  that
                     already had an operation in progress.

              EFAULT -- Bad address
                     The  system  detected an invalid address in attempting to
                     use an argument of a call.

              ENODEV -- Operation not supported by device
                     An attempt was made to apply an inappropriate function to
                     a device, for example, trying to read a write-only device
                     such as a printer.

              EHOSTDOWN -- Host is down
                     A socket operation failed because  the  destination  host
                     was down.

              EHOSTUNREACH -- No route to host
                     A  socket operation was attempted to an unreachable host.

       The following errors may be present in various BSD sources, but are not
       currently used in GNO:


              ENXIO -- No such device or address
                     Input  or  output  on a special file referred to a device
                     that did not exist, or made a request beyond  the  limits
                     of the device.  This error may also occur when, for exam-
                     ple, a tape drive is not online or no disk pack is loaded
                     on a drive.

              EDEADLK -- Resource deadlock avoided
                     An  attempt was made to lock a system resource that would
                     have resulted in a deadlock situation.

              EBUSY -- Resource busy
                     An attempt to use a system resource which was in  use  at
                     the time in a manner which would have conflicted with the
                     request.

              EXDEV -- Improper link
                     A hard  link  to  a  file  on  another  file  system  was
                     attempted.

              ENFILE -- Too many open files in system
                     Maximum  number of file descriptors allowable on the sys-
                     tem has been reached and a requests for an open cannot be
                     satisfied until at least one has been closed.

              ETXTBSY -- Text file busy
                     The  new  process was a pure procedure (shared text) file
                     which was open for writing by another process,  or  while
                     the  pure  procedure file was being executed an open call
                     requested write access.

              EFBIG -- File too large
                     The size of a file  exceeded  the  maximum  (about  2.1E9
                     bytes).

              EROFS -- Read-only file system
                     An  attempt  was  made  to modify a file or directory was
                     made on a file system that was read-only at the time.

              EMLINK -- Too many links
                     Maximum allowable hard links to a single  file  has  been
                     exceeded (limit of 32767 hard links per file).

              ELOOP -- Too many levels of symbolic links
                     A path name lookup involved more than 8 symbolic links.

              ENAMETOOLONG -- File name too long
                     A  component  of  a  path  name exceeded 255 (MAXNAMELEN)
                     characters, or an entire path name  exceeded  1023  (MAX-
                     PATHLEN-1) characters.

              ENOTEMPTY -- Directory not empty
                     A  directory  with entries other than .  and ..  was sup-
                     plied to a remove directory or rename call.

              EPROCLIM -- Too many processes

              EUSERS -- Too many users
                     The quota system ran out of table entries.

              EDQUOT -- Disc quota exceeded
                     A write to an ordinary file, the creation of a  directory
                     or  symbolic  link,  or the creation of a directory entry
                     failed because  the  user's  quota  of  disk  blocks  was
                     exhausted, or the allocation of an inode for a newly cre-
                     ated file failed because the user's quota of  inodes  was
                     exhausted.

              ESTALE -- Stale NFS file handle
                     An  attempt  was  made  to access an open file (on an NFS
                     filesystem) which is now unavailable as referenced by the
                     file  descriptor.  This may indicate the file was deleted
                     on the  NFS  server  or  some  other  catastrophic  event
                     occurred.

              EBADRPC -- RPC struct is bad
                     Exchange of RPC information was unsuccessful.

              ERPCMISMATCH -- RPC version wrong
                     The  version  of RPC on the remote peer is not compatible
                     with the local version.

              EPROGUNAVAIL -- RPC prog. not avail
                     The requested program is not  registered  on  the  remote
                     host.

              EPROGMISMATCH -- Program version wrong
                     The  requested version of the program is not available on
                     the remote host RPC.

              EPROCUNAVAIL -- Bad procedure for program
                     An RPC call was attempted for a procedure  which  doesn't
                     exist in the remote program.

              ENOLCK -- No locks available
                     A system-imposed limit on the number of simultaneous file
                     locks was reached.

              ENOSYS -- Function not implemented
                     Attempted a system call that is  not  available  on  this
                     system.


DEFINITIONS

       Process ID
              Each  active  process  in the system is uniquely identified by a
              non-negative integer called a process ID.  The range of this  ID
              is from 0 to 30000.

       Parent process ID
              A  new  process  is  created by a currently active process; (see
              fork(2)).  The parent process ID of a process is  initially  the
              process  ID  of its creator.  If the creating process exits, the
              parent process ID of each child is set to the  ID  of  a  system
              process, init.

       Process Group
              Each active process is a member of a process group that is iden-
              tified by a non-negative integer called the  process  group  ID.
              This  is the process ID of the group leader.  This grouping per-
              mits the signaling of related processes (see termios(4)) and the
              job control mechanisms of csh(1).

       Session
              A  session is a set of one or more process groups.  A session is
              created by a successful call  to  setsid(2),  which  causes  the
              caller  to  become  the only member of the only process group in
              the new session.

       Session leader
              A process that has created a new session by a successful call to
              setsid(2),  is known as a session leader.  Only a session leader
              may  acquire  a  terminal  as  its  controlling  terminal   (see
              termios(4)).

       Controlling process
              A  session  leader  with a controlling terminal is a controlling
              process.

       Controlling terminal
              A terminal that is associated with a session  is  known  as  the
              controlling terminal for that session and its members.

       Terminal Process Group ID
              A  terminal  may be acquired by a session leader as its control-
              ling terminal.  Once a terminal is associated  with  a  session,
              any  of the process groups within the session may be placed into
              the foreground by setting the terminal process group ID  to  the
              ID  of  the  process  group.  This facility is used to arbitrate
              between multiple jobs contending for  the  same  terminal;  (see
              csh(1) and tty(4)).

       Orphaned Process Group
              A  process group is considered to be orphaned if it is not under
              the control of a job control shell.  More precisely,  a  process
              group  is orphaned when none of its members has a parent process
              that is in the same session as the group, but is in a  different
              process  group.  Note that when a process exits, the parent pro-
              cess for its children is changed to be init, which is in a sepa-
              rate  session.  Not all members of an orphaned process group are
              necessarily orphaned processes (those whose creating process has
              exited).   The  process group of a session leader is orphaned by
              definition.

       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.

              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 Group Access List
              Access to system resources is governed by two values: the effec-
              tive  user  ID,  and the group access list.  The first member of
              the group access list is also known as the effective  group  ID.
              (In  POSIX.1,  the group access list is known as the set of sup-
              plementary group IDs, and it is unspecified whether  the  effec-
              tive group ID is a member of the 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)).   By
              convention,  the  effective  group  ID  (the first member of the
              group access list) is duplicated, so that  the  execution  of  a
              set-group-ID program does not result in the loss of the original
              (real) group ID.

              The group access list is a set of group IDs used only in  deter-
              mining  resource  accessibility.  Access checks are performed as
              described below in ''File Access Permissions''.

       Saved Set User ID and Saved Set Group ID
              When a process executes a new file, the effective user ID is set
              to  the  owner  of  the file if the file is set-user-ID, and the
              effective group ID (first element of the group access  list)  is
              set  to  the group of the file if the file is set-group-ID.  The
              effective user ID of the process is then recorded as  the  saved
              set-user-ID,  and  the  effective  group  ID  of  the process is
              recorded as the saved set-group-ID.  These values may be used to
              regain  those  values  as  the  effective user or group ID after
              reverting to the real ID  (see  setuid(2)).   (In  POSIX.1,  the
              saved  set-user-ID  and saved set-group-ID are optional, and are
              used in setuid and setgid, but this does not work as desired for
              the super-user.)

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

       Special Processes
              The processes with process IDs of 0, 1, and 2 are special.  Pro-
              cess  0  is the scheduler.  Process 1 is the initialization pro-
              cess init, and is the ancestor of every  other  process  in  the
              system.  It is used to control the process structure.  Process 2
              is the paging daemon.

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

       File Name
              names consisting of up to 255  (MAXNAMELEN)  characters  may  be
              used to name an ordinary file, special file, or directory.

              These characters may be selected from the set of all ASCII char-
              acter excluding 0 (NUL) and the ASCII code for / (slash).   (The
              parity bit, bit 7, must be 0.)

              Note  that it is generally unwise to use *, ?, [ or ] 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 1024  (MAXPATHLEN)
              characters.

              If  a  path  name begins with a slash, the path search begins at
              the root directory.  Otherwise, the search begins from the  cur-
              rent working directory.  A slash by itself names the root direc-
              tory.  An empty pathname refers to the current 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 direc-
              tory and a current working directory for the purpose of  resolv-
              ing  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.
              (Note:  even  the  super-user  cannot  execute  a non-executable
              file.)

              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.

       Sockets and Address Families

              A socket is an endpoint  for  communication  between  processes.
              Each socket has queues for sending and receiving data.

              Sockets  are typed according to their communications properties.
              These properties include whether messages sent and received at a
              socket require the name of the partner, whether communication is
              reliable, the format used in naming message recipients, etc.

              Each instance of the system supports some collection  of  socket
              types;  consult  socket(2)  for more information about the types
              available and their properties.

              Each instance of the system supports some number of sets of com-
              munications  protocols.  Each protocol set supports addresses of
              a certain format.  An Address Family is the set of addresses for
              a  specific group of protocols.  Each socket has an address cho-
              sen from the address family in which the socket was created.


SEE ALSO

       intro(3), perror(3), the GNO Kernel Reference Manual.



GNO                             29 January 1997                       INTRO(2)

Man(1) output converted with man2html