Content-type: text/html
Man page of intro
intro
Section: System Calls (2)
Index
Return to Main Contents
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:
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.
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.
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.
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.
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.
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.
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.
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}.
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).
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.
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.
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.
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.
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.
A process is recognized as a superuser process and is granted
special privileges if its effective user ID is 0.
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.
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.
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.
Indicates that the specified address is already in use.
Indicates that the specified address is not available from
the local machine.
Indicates that the addresses in the specified address family
are not supported by the protocol family.
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()).
Indicates that an operation was attempted on a non-blocking
object for which an operation was already in progress.
Indicates that a socket or file descriptor parameter is invalid.
Indicates that the next STREAMS message is of the wrong type.
Indicates that the NFS has encountered a Remote Procedure
Call request or response that is invalid or that cannot be decoded.
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.
Indicates that a pending AIO (asynchronous input/output) operation
was canceled.
Indicates either that the child process does not exist, or
that the requested child process information is unavailable.
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.
Indicates that the connection request was refused.
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.
Indicates either a probable deadlock condition, or that the
requested lock is owned by someone else.
Indicates that a required destination address was omitted
from an operation on a socket.
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.
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).
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.
Indicates that the request element (for example, a file or
a semaphore) already exists.
Indicates that the requested address is in some way invalid,
for example, out of bounds.
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.
Indicates that a socket operation failed because the destination
host was down.
Indicates that a socket operation failed because no route
could be found to the host.
Indicates that the requested semaphore or message queue ID
has been removed from the system.
Indicates that a wide character code does not correspond to
a valid character or an invalid multibyte character sequence was detected.
Indicates that a lengthy operation on a non-blocking object
is now in progress.
Indicates that an interruptible function's process was interrupted
by a signal that the process caught.
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()).
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.
Indicates that the socket is already connected.
Indicates either that the request was for a write access to
a file but the specified filename was actually a directory, or that the function
was trying to rename a directory as a file.
Indicates that too many links were encountered in translating
a pathname.
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.
Indicates that the number of links would exceed LINK_MAX.
Indicates that the message is too large to be sent all at
once, as the socket requires.
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.
Indicates that the pathname argument exceeds PATH_MAX (currently 1024), or a pathname component exceeds NAME_MAX (255).
Indicates that a socket operation has encountered a network
that is down.
Indicates that the network connection dropped when the remote
host reset it by rebooting.
Indicates that no route to the network or host exists.
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.
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.
Indicates that there is no message on the stream head read
queue.
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.
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()).
Indicates that the specified file has appropriate access permissions
but has an improper format, such as an unrecognizable object file format.
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.
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()).
Indicates that a message of the requested type does not exist
and the IPC_NOWAIT flag is set.
Indicates that the requested socket option is unknown and
the protocol is unavailable.
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()).
Indicates that no more STREAMS resources are available.
Indicates that the file descriptor is not associated with
a stream.
Indicates that the specified package does not contain the
named symbol.
Indicates an attempt to use a system call that is not implemented.
Indicates that the specified parameter is not or does not
point to a block device.
Indicates that the socket is not connected.
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.
Indicates that a directory is not empty during a file system
operation that requires an empty directory.
Indicates that the specified socket parameter refers to a
file, not a socket.
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()).
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.
Indicates either that the socket does not support the requested
operation, or that the socket cannot accept the connection.
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()).
Indicates that the selected protocol family is unconfigured
or unimplemented.
Indicates that an attempt was made to write to a pipe or FIFO
that was not open for reading by any process.
Indicates that a Remote Procedure Call (RPC) requested a server
to perform an unimplemented procedure. The error is through NFS.
Indicates that a Remote Procedure Call (RPC) requested a server
to execute an unsupported version of a program. The error is through NFS.
Indicates that a Remote Procedure Call (RPC) requested a server
to execute an unsupported program. The error is through NFS.
Indicates an error in STREAMS protocol.
Indicates that either the socket or the protocol is not supported.
Indicates that the specified protocol does not support the
requested type of socket.
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.
Indicates a server's attempt to handle an NFS request by generating
a request to another NFS server, which is not allowed.
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.
Indicates that a Remote Procedure Call (RPC) requested a server
to use an unsupported version of the RPC mechanism. The error is through
NFS.
Indicates that data cannot be sent to a socket because it
has been shut down.
Indicates that the socket type is not supported.
Indicates that an invalid seek operation was requested for
a pipe (FIFO), socket, or multiplexed special file (lseek()).
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.
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.
Indicates that a system call timed out in a STREAMS operation.
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.
Indicates that there are too many references to some kernel-level
object. The associated resource has presumably run out.
Indicates that there are too many users, as evidenced by a
full quota table.
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.
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].
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
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- DEFINITIONS
-
- RETURN VALUES
-
- ERRORS
-
- SEE ALSO
-
This document was created by
man2html,
using the manual pages.
Time: 02:40:12 GMT, October 02, 2010