 |
Index for
Section 2 |
|
 |
Alphabetical
listing for I |
|
 |
Bottom of
page |
|
intro(2)
NAME
intro, errno - Introduction to system calls
SYNOPSIS
#include <errno.h>
DESCRIPTION
Section 2 describes the Tru64 UNIX system calls, which are the entries into
the operating system kernel.
Some reference pages in this section may contain suffixes to allow their
files to exist with those of other reference pages having the same base
name and section number. When used, suffixes are made up of one to four
letters. See the man(1) reference page for more information on suffixes.
DEFINITIONS
The following terms are used in Section 2:
Descriptor
An integer assigned by the system when a file is referenced by the
open, dup, or pipe calls, or a socket is referenced by the socket or
socketpair calls. The descriptor uniquely identifies an access path to
that file or socket from a given process or any of its children.
Directory
A directory is a special type of file that contains references to other
files, called links. By convention, a directory contains at least two
links called dot (.) and dot-dot (..). Dot refers to the directory
itself and dot-dot refers to its parent directory.
Effective User Id, Effective Group Id, and Access Groups
Access to system resources is governed by 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 can be
modified through execution of a set-user-ID or set-group-ID file, or
possibly by one of its ancestors. For more information, see execve(2).
The group access list is an additional set of group IDs used only in
determining resource accessibility. Access checks are performed as
defined under the term File Access Permissions.
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
can be changed with the chmod call.
File access is separated into three types: read, write, and execute.
Directory files use the execute permission to control whether or not
the directory can 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, and 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 in the following instances:
· The process's effective user ID is that of the superuser.
· 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, but 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 the 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.
Read, write, and execute/search permissions on a file are not granted,
as follows:
· If the process is trying to execute an image and the file system
is mounted no execute, execute permission is denied.
· If the process's effective UID is not root, the process is
attempting to access a character or block special device, and the
file system is mounted with nodev, access is denied.
· If the process's effective UID is not root, the process is trying
to execute an image with the setuid or setgid bit set in the
file's permissions, and the file system is mounted nosuid, execute
permission is denied.
Filename
A name consisting of 1 to {NAME_MAX} bytes used to name an ordinary
file, special file, or directory.
The characters composing the name can be selected from the set of all
character values, excluding the slash character (/) and the null
character (0). The filenames dot (.) and dot-dot (..) have special
meaning.
Avoid using asterisks (*), question marks (?), or brackets ([ ]) as
part of filenames because of the special meaning attached to these
characters by the shell.
Parent Process ID
A new process is created by a currently active process. For further
information, see fork(2). The parent process ID of a process is the
process ID of its creator.
Pathname
A pathname is a string that is used to identify a file. A pathname
consists of, at most, {PATH_MAX} bytes, including the terminating null
character. A pathname has an optional beginning slash, followed by zero
or more filenames separated by slashes. If the pathname refers to a
directory, it may also have one or more trailing slashes. Multiple
successive slashes are considered the same as one slash.
If a pathname begins with a slash, the path search begins at the root
directory of the process. Otherwise, the search begins from the
current working directory.
The special filename dot (.) refers to the directory specified by its
predecessor. The special filename dot-dot (..) refers to the parent
directory of its predecessor directory. As a special case, in the root
directory, dot-dot may refer to the root directory itself.
A slash by itself names the root directory. A null pathname is
invalid.
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 0 to
{PROC_MAX}.
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. For more information see the job control mechanisms
described in csh(1).
Real User ID and Real Group ID
Each user on the system is identified by a positive integer called 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 group is called the real
group ID.
All processes have a real user ID and real group ID. These are
initialized from the equivalent attributes of the parent process.
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 does not need to be the root
directory of the root file system.
Session
Each process group is a member of a session. A process is considered
to be a member of the session of which its process group is a member.
Typically there is one session per login.
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 determine whether messages sent and received at a socket
require the name of the partner, if communication is reliable, and if
the format is used in naming message recipients.
Each instance of the system supports some collection of socket types.
See socket(2) for more information about the types available and their
properties.
Each instance of the system supports some number of sets of
communications 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 chosen from the address family in which the
socket was created.
Special Processes
Those processes that have a process ID of 0, 1, and 2 are considered
special processes. Process 0 is the scheduler. Process 1 is the
initialization process init, which is the ancestor of every other
process in the system and controls the process structure. Process 2 is
the exception handler.
Superuser
A process is recognized as a superuser process and is granted special
privileges if its effective user ID is 0.
tty Group ID
Each active process can be a member of a terminal group that is
identified by a positive integer called the tty group ID. This grouping
is used to arbitrate between multiple jobs contending for the same
terminal. For more information, see csh(1) and tty(7).
RETURN VALUES
Most system calls have one or more return values. An error condition is
indicated by an otherwise impossible return value. This value is usually
-1. All return codes and values from functions are of type int unless
otherwise noted.
ERRORS
When a function returns an error condition, it also stores an error number
in the external variable errno. This variable is not cleared on successful
calls. Thus, you should test errno only after an error has occurred. Refer
to errno(5) for information about using the errno variable. The remainder
of this section lists in alphabetical order the symbolic codes for errno
values, along with associated messages and explanations. Some codes
represent more than one type of error. For example, [E2BIG] can indicate
that the specified argument size has exceeded the system limit of ARG_MAX,
or that the specified number of sembuf structures has exceeded a predefined
limit.
[E2BIG] Arg list too long
Indicates that the specified argument and environment lists exceed the
system limit of ARG_MAX bytes, or the number of bytes in the message
exceeds the predefined limit.
[EACCES] Permission denied
Indicates that the requested operation did not have the proper access
permissions. This error may also indicate one or more of the following:
· The named file is not an ordinary file (acct()).
· The operation would cause the parent directory or process's
information level to float such that it would no longer be
dominated by the directory or process's sensitivity level.
· The requested file is not available for read or write access.
· The process is attempting to mount on a multilevel child
directory.
· The value of the process ID argument matches the process ID of a
child process of the calling process and the child process has
successfully executed one of the exec functions (setpgid()).
· The function is trying to manipulate two files on two different
file systems.
· An open with write mode has been attempted to a write protected
tape.
[EADDRINUSE] Address already in use
Indicates that the specified address is already in use.
[EADDRNOTAVAIL] Can't assign requested address
Indicates that the specified address is not available from the local
machine.
[EAFNOSUPPORT] Address family not supported by protocol family
Indicates that the addresses in the specified address family are not
supported by the protocol family.
[EAGAIN] Operation would block
Indicates that the requested resource, such as a lock or a process, is
temporarily unavailable. This error may also indicate one or both of
the following:
· If the O_NONBLOCK flag is set for the requested function, the
process would be delayed in a read or write operation.
· The specified time has elapsed (pthread_cond_timedwait()).
[EALREADY] Operation already in progress
Indicates that an operation was attempted on a non-blocking object for
which an operation was already in progress.
[EBADF] Bad file number
Indicates that a socket or file descriptor parameter is invalid.
[EBADMSG] Next message has wrong type
Indicates that the next STREAMS message is of the wrong type.
[EBADRPC] RPC structure is bad
Indicates that the NFS has encountered a Remote Procedure Call request
or response that is invalid or that cannot be decoded.
[EBUSY] Device busy
Indicates one or more of the following errors:
· The requested element is currently unavailable, or the associated
system limit was exceeded.
· For NFS files, the requested device or directory is in use by
another process.
[ECANCELED] Operation canceled
Indicates that a pending AIO (asynchronous input/output) operation was
canceled.
[ECHILD] No child processes
Indicates either that the child process does not exist, or that the
requested child process information is unavailable.
[ECONNABORTED] Software caused connection abort
Indicates that the software caused a connection abort because there is
no space on the socket's queue and the socket cannot receive further
connections.
[ECONNREFUSED] Connection refused
Indicates that the connection request was refused.
[ECONNRESET] Connection reset by peer
Indicates that a connection was forcibly reset (closed) by a peer. The
situation normally results when a timeout or a reboot causes the loss
of the connection on the remote socket.
[EDEADLK] Resource deadlock avoided
Indicates either a probable deadlock condition, or that the requested
lock is owned by someone else.
[EDESTADDRREQ] Destination address required
Indicates that a required destination address was omitted from an
operation on a socket.
[EDIRTY] Mounting a dirty fs w/o force
Indicates an attempt to mount a dirty file system, one on which a
consistency check has not or cannot be made. A dirty file system can
be mounted by force only if the M_FMOUNT flag is included on the
mount() call.
[EDOM] Argument out of domain
Indicates that x and/or y are either Not a Number (NaN), or that they
are in some other way unacceptable (for example, they exceed system
limits).
[EDQUOT] File system quota exceeded
A write has failed because the user's disk block quota is exhausted or
an open that would create a file has failed because the user's inode
quota is exhausted.
[EEXIST] File exists
Indicates that the request element (for example, a file or a semaphore)
already exists.
[EFAULT] Bad address
Indicates that the requested address is in some way invalid, for
example, out of bounds.
[EFBIG] File too large
Indicates either that the file size exceeds the process's file size
limit, or that the requested semaphore number is invalid. Valid
semaphore numbers are greater than 0 (zero) and less than the specified
number of semaphores.
[EHOSTDOWN] Host is down
Indicates that a socket operation failed because the destination host
was down.
[EHOSTUNREACH] Host is unreachable
Indicates that a socket operation failed because no route could be
found to the host.
[EIDRM] Identifier removed
Indicates that the requested semaphore or message queue ID has been
removed from the system.
[EILSEQ]
Indicates that a wide character code does not correspond to a valid
character or an invalid multibyte character sequence was detected.
[EINPROGRESS] Operation now in progress
Indicates that a lengthy operation on a non-blocking object is now in
progress.
[EINTR] Interrupted system call
Indicates that an interruptible function's process was interrupted by a
signal that the process caught.
[EINVAL] Invalid argument
Indicates that an invalid argument was passed to the function (such as,
the requested argument does not exist or is out of bounds or is not a
regular file, or that the result would be invalid). This error may also
indicate one or more of the following:
· The requested socket is not accepting connections (accept()) or is
already bound (bind()).
· The specified superblock had a bad magic number or a block size
that was out of range (mount()).
· The requested parameter is a lock/unlock parameter, but the
element to be locked is already locked/unlocked (plock()).
· The kernel has not been compiled with the QUOTA option (quota()).
· An attempt was made to ignore or supply a handler for the SIGKILL,
SIGSTOP, and SIGCONT signals (sigaction()).
· The requested device was not configured as a swap device or does
not allow paging (swapon()).
· The requested device is not mounted or local (mount()).
[EIO] I/O error
Indicates one of the following:
· A read or write physical I/O error. These errors do not always
occur with the associated function, but can occur with the
subsequent function.
· The requested parameter does not have an appropriate value, or is
invalid (ptrace()).
· On a terminal, EIO means the following: the process is running in
the background, the process did a write() to its controlling
terminal, and TOSTOP is set on the terminal, but the process is
neither ignoring nor blocking SIGTTOU, and the process group of
the process is orphaned, i.e. a child of pid 1.
[EISCONN] Socket is already connected
Indicates that the socket is already connected.
[EISDIR] Is a directory
Indicates either that the request was for a write access to a file but
the specified file name was actually a directory, or that the function
was trying to rename a directory as a file.
For an NFS client, an attempt was made to read a directory that resides
on an NFS server by using a function, such as read(). In this case,
readdir() or getdirentries() is required to read the directory.
[ELOOP] Too many levels of symbolic links
Indicates that too many links were encountered in translating a
pathname.
[EMFILE] Too many open files
Indicates one or more of the following errors:
· Too many file descriptors are open (exceeding OPEN_MAX).
· No space remains in the mount table.
· The attempt to attach a shared memory region exceeded the maximum
number of attached regions allowed for any one process.
This error indicates that a per process limit has been exceeded. See
[ENFILE] for the case when a system-wide limit has been exceeded.
[EMLINK] Too many links
Indicates that the number of links would exceed LINK_MAX.
[EMSGSIZE] Message too long
Indicates that the message is too large to be sent all at once, as the
socket requires.
[EMTIMERS] Too many timers
Indicates that the number of timers exceeds the value defined by the
TIMER_MAX system variable. This error is available only in the
realtime kernel.
[ENAMETOOLONG] File name too long
Indicates that the pathname argument exceeds PATH_MAX (currently 1024),
or a pathname component exceeds NAME_MAX (255).
[ENETDOWN] Network is down
Indicates that a socket operation has encountered a network that is
down.
[ENETRESET] Network dropped connection on reset
Indicates that the network connection dropped when the remote host
reset it by rebooting.
[ENETUNREACH] Network is unreachable
Indicates that no route to the network or host exists.
[ENFILE] File table overflow
Indicates either that the system file table is full, or that there are
too many files currently open in the system.
This error indicates that a system-wide limit has been exceeded. See
[EMFILE] for the case when a per process limit has been exceeded.
[ENOBUFS] No buffer space available
Indicates insufficient resources, such as buffers, to complete the
call. Typically, a call used with sockets has failed due to a shortage
of message or send/receive buffer space.
[ENODATA] No message on stream head read q
Indicates that there is no message on the stream head read queue.
[ENODEV] No such device
Indicates one or more of the following errors:
· The file descriptor refers to an object that cannot be mapped.
· The requested block-special device file does not exist.
· A file system is unmounted.
[ENOENT] No such file or directory
Indicates one or more of the following errors:
· The specified file pathname or directory pathname does not exist
or points to an empty string.
· The O_CREAT flag is set and the named file or path prefix does not
exist (open()).
· A message queue identifier does not exist for a message key
identifier and the IPC_CREAT flag is not set for the function
(msgget()).
· A semaphore ID does not exist for a semaphore key identifier and
the IPC_CREAT flag is not set for the function (semget()).
· A shared memory region ID does not exist for a shared memory
region key identifier and the IPC_CREAT flag is set for the
function (shmeget()).
[ENOEXEC] Exec format error
Indicates that the specified file has appropriate access permissions
but has an improper format, such as an unrecognizable object file
format.
[ENOLCK] No locks available
Indicates that the lock table is full because too many regions are
already locked, or satisfying a lock (or unlock) request would result
in the number of locked regions in the system exceeding a system-
imposed limit.
[ENOMEM] Not enough space
Indicates that insufficient memory is available for the requested
function. This error may indicate one or more of the following errors:
· Mapped region attribute was set and part of the specified address
range is already allocated (mmap()).
· The specified range is invalid for a process's address space or
the range specifies one or more unmapped pages (msync()).
· A new semaphore could not be created (msem_init()).
[ENOMSG] No message of desired type
Indicates that a message of the requested type does not exist and the
IPC_NOWAIT flag is set.
[ENOPROTOOPT] Option not supported by protocol
Indicates that the requested socket option is unknown and the protocol
is unavailable.
[ENOSPC] No space left on device
Indicates one or more of the following errors:
· Not enough space to extend the file system or device for write
operations on a file, directory, or both.
· The madvise() function tried to reserve resources that were not
available to be reserved.
· The system-imposed limit of the maximum number of allowed message
queue identifiers has been exceeded (msgget()).
· An attempt to create a semaphore ID exceeded the system-wide limit
on the semaphore table (semget()).
· An attempt to create a new shared memory region ID exceeded the
system-wide limit of maximum IDs (shmget()).
· The system-defined limit on the number of processes using SEM_UNDO
was exceeded (semop()).
[ENOSR] Out of STREAMS resources
Indicates that no more STREAMS resources are available.
[ENOSTR] fd not associated with a stream
Indicates that the file descriptor is not associated with a stream.
[ENOSYM] Unresolved symbol name
Indicates that the specified package does not contain the named symbol.
[ENOSYS] Function not implemented
Indicates an attempt to use a system call that is not implemented.
[ENOTBLK] Block device required
Indicates that the specified parameter is not or does not point to a
block device.
[ENOTCONN] Socket is not connected
Indicates that the socket is not connected.
[ENOTDIR] Not a directory
Indicates that a component of the path parameter exists but is not a
directory, or an operation is being performed from a directory to a
nonexistent directory.
[ENOTEMPTY] Directory not empty
Indicates that a directory is not empty during a file system operation
that requires an empty directory.
[ENOTSOCK] Socket operation on non-socket
Indicates that the specified socket parameter refers to a file, not a
socket.
[ENOTTY] Not a typewriter
Indicates one or more of the following errors:
· The file descriptor's file is not a terminal.
· The calling process does not have a controlling terminal.
· The controlling terminal is no longer associated with the calling
process session (tcsetpgrp()).
· The specified open descriptor is not associated with a character-
special device or the specified request does not apply to the kind
of object that the specified open descriptor references (ioctl()).
[ENXIO] No such device or address
Indicates one or more of the following errors:
· The specified address, major device number, or channel is out of
valid range.
· No more channels are available (open()).
· The named file is a character-special or block-special file and
the associated device does not exist (open()).
· The O_NONBLOCK flag is set, the named file is FIFO, O_WRONLY is
set, and no process has the file open for reading (open()).
· The specified tape drive is offline or a disk pack is not loaded
in the specified disk drive.
[EOPNOTSUPP] Operation not supported on socket
Indicates either that the socket does not support the requested
operation, or that the socket cannot accept the connection.
[EPERM] Not owner
Indicates that the function attempted to perform an operation for which
it did not have appropriate privileges, or the caller was not the owner
of the requested element or superuser. This error may also indicate one
or both of the following:
· The calling process was not in the same session as the target
process (setpgid()).
· The calling process is already the process group leader or the
process group ID of a process other than the calling process
matches the process ID of the calling process (setsid()).
[EPFNOSUPPORT] Protocol family not supported
Indicates that the selected protocol family is unconfigured or
unimplemented.
[EPIPE] Broken pipe
Indicates that an attempt was made to write to a pipe or FIFO that was
not open for reading by any process.
[EPROCUNAVAIL] Bad procedure for program
Indicates that a Remote Procedure Call (RPC) requested a server to
perform an unimplemented procedure. The error is through NFS.
[EPROGMISMATCH] Program version wrong
Indicates that a Remote Procedure Call (RPC) requested a server to
execute an unsupported version of a program. The error is through NFS.
[EPROGUNAVAIL] RPC program not available
Indicates that a Remote Procedure Call (RPC) requested a server to
execute an unsupported program. The error is through NFS.
[EPROTO] Error in protocol
Indicates an error in STREAMS protocol.
[EPROTONOSUPPORT] Protocol not supported
Indicates that either the socket or the protocol is not supported.
[EPROTOTYPE] Protocol wrong type for socket
Indicates that the specified protocol does not support the requested
type of socket.
[ERANGE] Result too large
Indicates one or more of the following errors:
· The result would exceed the system-defined limits or cause an
overflow (value too large) or an underflow (value too small).
· A specified parameter is greater than 0 (zero) but smaller than
the length of the pathname + 1 (getcwd()).
· The symbol value cannot be represented as an absolute value.
· The magnitude of x is such that total or partial loss of
significance resulted.
[EREMOTE] Item is not local to host
Indicates a server's attempt to handle an NFS request by generating a
request to another NFS server, which is not allowed.
[EROFS] Read-only file system
Indicates one or more of the following errors:
· The operation requested was to be performed on a read-only file
system.
· An attempt was made to activate a paging file on a read-only file
system.
· The named file resides on a read-only file system and the file
type requires write access.
[ERPCMISMATCH] RPC version is wrong
Indicates that a Remote Procedure Call (RPC) requested a server to use
an unsupported version of the RPC mechanism. The error is through NFS.
[ESHUTDOWN] Can't send after socket shutdown
Indicates that data cannot be sent to a socket because it has been shut
down.
[ESOCKTNOSUPPORT] Socket type not supported
Indicates that the socket type is not supported.
[ESPIPE] Illegal seek
Indicates that an invalid seek operation was requested for a pipe
(FIFO), socket, or multiplexed special file (lseek()).
[ESRCH] No such process
Indicates one or more of the following errors:
· The requested process or child process ID is invalid or not in
use.
· No disk quota is found for the specified user.
· The specified thread ID does not refer to an existing thread.
[ESTALE] Stale NFS file handle
Indicates one or more of the following errors:
· An opened file was deleted by the server or another client.
· The directory that contains an opened file was either unmounted or
unexported by the server.
· A client cannot open a file because the server has unmounted or
unexported the remote directory.
[ETIME] System call timed out
Indicates that a system call timed out in a STREAMS operation.
[ETIMEDOUT] Connection timed out
Indicates one or more of the following errors:
· The requested attempt at a connection timed out before a
connection was established.
· For NFS files that are mounted with the soft option, either the
server is down or there is a network problem.
[ETOOMANYREFS] Too many references; can't splice
Indicates that there are too many references to some kernel-level
object. The associated resource has presumably run out.
[EUSERS] Too many users
Indicates that there are too many users, as evidenced by a full quota
table.
[EVERSION] Version mismatch
Indicates a version number mismatch between loader interfaces, such as
between an old library and a new loader when the way libraries work has
been changed.
[EWOULDBLOCK] Operation would block
Indicates one or more of the following errors:
· The socket is marked nonblocking and no connections are waiting to
be accepted.
· The socket is marked nonblocking and connection cannot be
immediately completed.
· The file is locked and the function is instructed not to block
when locking.
· The socket is marked as nonblocking and no space is available for
the specified function.
See also [EAGAIN].
[EXDEV] Cross-device link
Indicates either that a hard link was attempted between two file
systems, or that a filename to be renamed by rename() is on a different
file system from the link to which it is to be renamed.
SEE ALSO
cc(1), csh(1), intro(3), perror(3), errno(5), tty(7)
|
Index for
Section 2 |
|
|
Alphabetical
listing for I |
|
 |
Top of
page |
|