NAME

intro − 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 returned value.  This is almost always −1; the individual descriptions specify the details.  An error number is also made available in the external variable errno. Errno is not cleared on successful calls, so it should be tested only after an error has been indicated.

Each system call description attempts to list all possible error numbers.  The following is a list of error names as defined in <errno.h>.  The actual error numbers are system type dependant. 

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.

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.

ESRCH  No such process
No process can be found corresponding to that specified by pid in kill or ptrace.

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

EIO  I/O error
Some physical I/O error has occurred. This error may in some cases occur on a call following the one to which it actually applies.

ENXIO  No such device or address
I/O on a special file refers to a subdevice which does not exist, or beyond the limits of the device. It may also occur when, for example, a tape drive is not on-line or no disk pack is loaded on a drive.

E2BIG  Arg list too long
An argument list longer than 5,120 bytes is presented to a member of the exec family.

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

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

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

EAGAIN  Resource temporarily unavailable, try again later
For example, a fork failed because the system’s process table is full or the user is not allowed to create any more processes. 

ENOMEM  Not enough space
During an exec, brk, or sbrk, a program asks for more space than the system is able to supply. This is not a temporary condition; the maximum space size is a system parameter. The error may also occur if the arrangement of text, data, and stack segments requires too many segmentation registers, or if there is not enough swap space during a fork.

EACCES  Permission denied
An attempt was made to access a file, or other object, in a way forbidden by the security policy.

EFAULT  Bad address
The system encountered a hardware fault in attempting to use an argument of a system call.

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

EBUSY  Device or resource busy
An attempt was made 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, active text segment). It will also occur if an attempt is made to enable accounting when it is already enabled. The device or resource is currently unavailable.

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

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

ENODEV  No such device
An attempt was made to apply an inappropriate system call to a device; e.g., read a write-only device.

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

EISDIR  Is a directory
An attempt was made to write on a directory.

EINVAL  Invalid argument
Some invalid argument (e.g., dismounting a non-mounted device; mentioning an undefined signal in signal, or kill; reading or writing a file for which lseek has generated a negative pointer). Also set by the math functions described in the (3M) entries of this manual.

ENFILE  File table or inode table overflow
The system file table or the system inode table is full, and temporarily no more opens can be accepted. 

EMFILE  Too many open files
A process may not have more files descriptors open at a time, than specified by its current limit for open file descriptors (see getrlimit(2)). 

ENOTTY  Not a character device
An attempt was made to ioctl(2) a file that is not a special character device. 

ETXTBSY  Text file busy
An attempt was made to execute a pure-procedure program that is currently open for writing. Also an attempt to open for writing a pure-procedure program that is being executed.

EFBIG  File too large
The size of a file exceeded the maximum file size (1,082,201,088 bytes) or ULIMIT; see ulimit(2). 

ENOSPC  No space left on device
During a write to an ordinary file, there is no free space left on the device.

ESPIPE  Illegal seek
An lseek was issued to a pipe.

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

EMLINK  Too many links
An attempt to make more than the maximum number of links (1000) to a file.

EPIPE  Broken pipe
A write on a pipe for which there is no process to read the data. This condition normally generates a signal; the error is returned if the signal is ignored.

EDOM  Math argument
The argument of a function in the math package (3M) is out of the domain of the function.

ERANGE  Result too large
The value of a function in the math package (3M) is not representable within machine precision.

ENOMSG  No message of desired type
An attempt was made to receive a message of a type that does not exist on the specified message queue; see msgop(2). 

EIDRM  Identifier Removed
This error is returned to processes that resume execution due to the removal of an identifier from the file system’s name space (see msgctl(2), semctl(2), and shmctl(2)).

EWOULDBLOCK  Operation would block
An operation which would cause a process to block was attempted on a object in non-blocking mode (see ioctl (2)). 

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

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

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.

EPROTOTYPE  Protocol wrong type for socket
A protocol was specified which does not support the semantics of the socket type requested. For example you cannot use the ARPA Internet UDP protocol with type SOCK_STREAM.

ENOPROTOOPT  Bad protocol option
A bad option 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 on socket
For example, trying to accept a connection on a datagram socket. 

EPFNOSUPPORT  Protocol family not supported
The protocol family has not been configured into the system 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 PUP Internet addresses with ARPA Internet protocols.

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

EADDRNOTAVAIL  Can’t 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 network.

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 normally results from the peer executing a shutdown (2) call. 

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

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 other than the connected party. 

ENOTCONN  Socket is not connected
An request to send or receive data was disallowed because the socket is not connected.

ESHUTDOWN  Can’t 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. 

ETOOMANYREFS  Too many references: can’t splice

ETIMEDOUT  Connection timed out
A connect 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 which is inactive on the foreign host.

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 characters, or an entire path name exceeded 1023 characters.

EHOSTDOWN  Host is down
The host machine is not up.

EHOSTUNREACH  No route to host
The host machine cannot be reached.

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

EPROCLIM  Too many processes

EUSERS  Too many users
The quota table is full.

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 created file failed because the user’s quota of inodes was exhausted. 

EDEADLK  Deadlock
A deadlock situation was detected and avoided. This error pertains to file and record locking.

EDEADLK  System Call does not exist
The system call attempted does is not supported on this system.

ECHNRST  X.25 channel reset
The X.25 channel was reset by a peer or due to a processing error.

EXLNERR  X.25 link error

EXNFST  X.25 Fast Select error
An X.25 call request improperly used the Fast Select facility

EXFORBID  no read/write on X.25 channel 0
An attempt was made to read or write from X.25 channel 0, which is used strictly for administrative purposes.

EXCANCEL  get next X.25 call canceled
An X.25 get next call request was canceled due to timeout.

EXCOLLIN  X.25 call collision
An X.25 incoming call was received on a channel which issued a call request.

EXNONE  X.25 circuit does not exist
An X.25 request was made for a circuit that no longer exists.

EXARATT  X.25 circuit already attached
An attempt was made to attach to a permanent virtual circuit which is already attached.

EXBADCOM  X.25 communication error
 X.25 level 2 is not operational.

EXBADPAC   invalid packet size in X.25 facility
An X.25 call request was made with an invalid packet size facility.

EXBADPAR  X.25 - bad parameters
An X.25 request was made specifying invalid parameters.

EXBADSTATE  the X.25 channel is in the wrong state
The X.25 request cannot be executed in the current channel state.

EXBADWIN   invalid window size in X.25 facility
An X.25 call request was made with an invalid window size facility.

EXWAS  X.25 circuit already detached
An attempt was made to detach  a permanent virtual circuit which is already detached.

EXEXMAX  X.25 circuit is not available
All X.25 circuits are currently utilized.

EXLNCON  X.25 link not configured
The X.25 link has not been configured and downloaded.

EXLNOP  X.25 link is not open
The X.25 link has not been opened.

EXLOBND  X.25 link number is out of bounds
The X.25 link number specified is invalid.

EXMULRQ  Multiple X.25 request for the same pid
Multiple X.25 requests have been issued simultaneously by the same process id.

EXNATT  X.25 circuit is not attached
A request was made on a permanent virtual circuit which has not been previously attached.

EXNOFAC  invalid X.25 facility
An X.25 call request was made using a facility which is not subscribed.

EXNRES  X.25 buffer resources not available
There are currently no X.25 buffers available.

EXRDEXCD  the X.25 read request threshold exceeded
The maximum number of outstanding X.25 read requests was exceeded.

EXTMOUT  the X.25  command has timed out
The X.25 command timer (e.g. xgcall) has expired with no reply from the destination.

EXWOVER  the X.25 window overflow
The X.25 send window has been exceeded.

EXCACLR  the X.25 circuit is being cleared
The X.25 call request was cleared by the peer.

EXRANGE  the X.25 index number is out of range
The X.25 circuit index number specified in the request was out of range.

ELNKDWN  the VIOC-BOP link is down
Level 2 is operational but the link connection can not be established.

EREREOPEN  the X.25 port is already open
Trying to open an already open X.25 port.

ERERECLOS  the X.25 port is already closed
Trying to close an already closed X.25 port.

ERTRYEX  X.25 retries exceeded
The X.25 command retry count has been exceeded with no reply from the destination.

ELNKRST  the X.25 link has been reset
The X.25 link has been reset by a peer or due to a communication error.

ELIDLE  the X.25 link is idle
The X.25 link has been idle for a specified period of time, action will be taken to restart the link.

EIDLESTOP  the X.25 link is no longer idle
The X.25 link had been idle and was recovered.

EBUFOK  X.25 buffer congestion relieved
X.25 buffers are now available.

XNERST  the X.25 circuit is in the reset state
The X.25 circuit is currently being reset, writes will be retransmitted when the reset is complete.

XNIL2E  X.25 level 2 error detected
An error has occurred during X.25 level 2 processing.

EREMBSY  the X.25 remote station is busy
An attempt was made to transmit data to a remote station that is currently unable to receive data.

EXNOACT  X.25 link or channel is not active
An X.25 request was made to a link or channel that is not currently active.

EXBADFAC  bad X.25 facility specified
An X.25 call request was made using an invalid facility.

EBUFLOW  the VIOC-BOP is low on buffers
The VIOC-BOP has reached its lower limit for receive buffers.

EVERR  the VIOC-BOP is down
An unresolvable condition has occurred on the VIOC-BOP, it is going offline

EXMIT  VIOC-BOP write error
An error occurred during a VIOC-BOP write, the frame was not transmitted.

EVOVRFL  VIOC-BOP overflow
The VIOC-BOP has received more frames than it can handle, overflow frames will be lost.

EBADCMP  bad X.25 component
A bad component was specified during the setting or retrieving of the X.25 configuration.

ESTALE  Stale NFS file handle
A client referenced an open file, when the file has been deleted.

EREMOTE  Too many levels of remote in path
An attempt was made to remotely mount a file system into a path which already has a remotely mounted component.

ENOLCK  No lock
In fcntl(2) the setting or removing of record locks on a file cannot be accomplished because there are no more record entries left on the system. 

ESDOPEN  SDLC open not complete
An operation was attempted on an SDLC device before the Set SDLC Parameters ioctl call was issued. 

ESDKBUF  SDLC kernel buffer error
A write operation on an SDLC device erroneously referenced a kernel buffer. 

ESDPU  SDLC PU number error
An invalid PU number was specified in a Set SDLC Parameters ioctl call. 

ESDADDR  SDLC link address error
An invalid SDLC address was specified in a Set SDLC Parameters ioctl call. 

ESDFRSIZE  SDLC frame size error
An invalid SDLC frame size was specified in a Set SDLC Parameters ioctl call. 

ESDENCODE  SDLC encoding error
An invalid SDLC encoding value was specified in a Set SDLC Parameters ioctl call. 

EPUBUF  SNA PU buffer format error
The buffer format in write call to an SNA PU was not valid. 

EPUAPPL  SNA PU application ID error
The application id contained in a write call buffer to an SNA PU was not valid. 

EPULUDOWN  SNA LU down error
The destination application (LU) referenced in a write call buffer to an SNA PU is not active. 

ELUINIT  SNA LU not initialized
An operation was attempted on an SNA LU device before the Define Interface ioctl call was issued. 

ELUPUDOWN  SNA PU down error
The destination application (PU) referenced in a write call buffer to an SNA LU is not active. 

ELUBUF  SNA LU buffer format error
The buffer format in write call to an SNA LU was not valid. 

ELUPUBAD  SNA PU number error
An invalid PU number was specified in a Define Interface ioctl call. 

EIOCANCEL  Async I/O operation cancelled
When the user requests that an asynchronous I/O operation be cancelled via acancel(2), the operation is cancelled if it is in a state where this can be accomplished.  EIOCANCEL is returned in the status location given to the aread(2) or awrite(2) call that initiated the operation. 

EAREQ  No async I/O request blocks available
An aread(2) or awrite(2) call was attempted but the system lacks the number of internal data structures necessary to manage the I/O request. 

ERNLOCK  Test address in non-locked region
The virtual address used in the badaddr(2) call is contained within a data or shared memory region that is not locked into memory (see plock(2)). 

ENDATREG  Test address in non-data region
The virtual address used in the badaddr(2) call is contained within a region that is neither a data nor a shared memory region. 

EPAGNV  Test address in non-valid page
The virtual address used in the badaddr(2) call is contained within a page that is currently not valid. 

EBADSPACE  Address not in specified space
The shmbind(2) operation invloves the notion of physical memory spaces (see below).  The actual physical range that is being bound on a shmbind operation is defined by the supplied starting physical address and the length of the shared memory region that is having the bind operation performed upon it.  The physical space that is targeted for binding is defined by the type argument supplied to the shmbind call.  EBADSPACE is returned whenever a shmbind call is made such that the some portion of the actual physical range being bound lies outside the physical space specified. 

EREGSTALE  Region contains stale information
The shared memory region referenced by the shared memory identifier shmid supplied to the shmbind(2) call has valid data pages that would be destroyed by the act of binding. 

ENORFMODE  Invalid IEEE Rounding/Format mode
The user process has attmepted to use an invlaid IEEE rounding/format mode.
 

ENOSTR  Not a stream
A putmsg(2) or getmsg(2) system call was attempted on a file descriptor that is not a STREAMS device. 

ETIME  Stream ioctl timeout
The timer set for a STREAMS ioctl(2) call has expired.  The cause of this error is device specific and could indicate either a hardware or software failure, or perhaps a timeout value that is too short for the specific operation.  The status of the ioctl(2) operation is indeterminate. 

ENOSR  No stream resources
During a STREAMS open(2), either no STREAMS queues or no STREAMS head data structures were available. 

ENOPKG  No package
This error occurs when users attempt to use a system call from a package which has not been installed.

EPROTO  Protocol error
Some protocol error occurred.  This error is device specific, but is generally not related to a hardware failure.

EBADMSG  Bad message
During a read(2), getmsg(2), or ioctl(2) I_RECVFD system call to a STREAMS device, something has come to the head of the queue that can’t be processed.  That something depends on the system call:
  read(2) - control information or a passed file descriptor. 
  getmsg(2) - passed file descriptor. 
  ioctl(2) - control or data information. 

DEFINITIONS

Subjects

In CX/SX, all users and all processes executing on behalf of the users are defined to be subjects.  Users only exist within the system as active processes descendent directly or indirectly from the user authentication process [see login(1)].  Subjects act upon objects available to them under the constraints of the system’s security policy. 

Objects

Objects are defined to be files, directories, devices, pipes, named pipes, message queues, shared memory segments, semaphores, sockets, binary semaphores, frequency based schedulers and processes (when receiving signals).  Each is defined more fully below. 

Security Policy

A subject inherits the clearance or classification assigned at login.  All descendent subjects (processes) inherit this classification, unless the classification is raised by the use of the privileged newpriv(1SX) command.  All objects created by a subject are marked with the subject’s current classification.  Mandatory protection is enforced based on clearances and classifications as described below.  (See File Access Permissions.) 

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 30,000. 

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. 

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 ID is the process ID of the group leader.  This grouping permits the signaling of related processes; see kill(2). 

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 terminate a group of related processes upon termination of one of the processes in the group; see exit(2) and signal(2). 

Real User ID and Real Group ID

Each user allowed on the system is identified by a positive integer called a real user ID. 

Each user is also a member of a group.  The group is identified by a positive integer called the real group ID. 

An active process has a real user ID and real group ID that are set to the real user ID and real group ID, respectively, of the user responsible for the creation of the process. 
 

User Identifier (UID)

Each user allowed on the system is identified by a positive integer (0 to 60000) called a user identifier (UID). 

Any active process is marked with the identifier (UID) of the user responsible for the creation of the process. 

User Attributes

The user identifier (UID) serves as an index into the passwd and clearances files to reference additional information (attributes) unique to the user: symbolic login name, password, default privilege (GID), home directory, preferred command interpreter (shell), the user’s security clearance, and optional (administrator defined) information such as the user’s full name, address, phone number, etc.  [See passwd(4SX) and clearances(1SX).]

Privilege Identifier (GID)

Each user is also authorized to operate with a set of possible access privileges.  The specific access privileges selected at any point in time is identified by the privilege identifier (GID). 

Each active process is marked with the privilege identifier (GID) selected via login(1SX), newpriv(1SX), or newgrp(1SX) by the user responsible for the creation of the process. 

Privilege Attributes

The privilege identifier (GID) serves as an index into the group and labels files to reference attributes common to all subjects and objects marked with the same privilege identifier (GID).  Such information includes: lists of users authorized to operate with the given privilege, the symbolic name of the privilege, the (discretionary) group identifier (DGID) used in computing discretionary access (usr/group/other), and the classification label of the object or the current effective clearance of the subject.  (See Security Label below.) 

Group Identifier (DGID)

Each user is also a member of one or more groups.  A group is a set of users that share similar access rights to a set of objects (i.e. need to know or need to share).  A group is identified by a positive integer called a group identifier (DGID).  Objects that are related by belonging to the same organization or project, for example, can be marked as being "owned by the group" by marking them with a privilege identifier (GID) associated with the DGID of the group.  Objects that are in the same group can share the same discretionary group DGID but use different GIDs if they differ in classification.  The group identifier (DGID) is used in computing discretionary access rights.  (See Discretionary Protection below.) 

Effective User ID and Effective Group ID

An active process has an effective user ID and an effective group ID that are used to determine file access permissions (see below).  The effective user ID and effective group ID are equal to the process’s real user ID and real group ID respectively, unless the process or one of its ancestors evolved from a file that had the set-user-ID bit or set-group ID bit set; see exec(2). 

Security Label

Associated with every object is a privilege identifier (GID) and associated with every GID is a security label.  A security label specifies at what Level and in which Categories an object is sensitive, or at which level and in which categories a subject is currently operating.  (See labels(4SX).) 

The system guarantees that all objects are marked at creation with the GID (and hence label) of the subject that created the object.  Further, the GID cannot be changed by an ordinary user to any other privilege identifier unless the new privilege is associated with a security label that matches or dominates the file’s current label.  Members of the privilege "secadm" may change the privilege identifier of the files they own to any other privilege.  Super-user may change the GID of anyone’s file to any GID. (B1 only)

Clearances and Classifications

The security label associated with a subject (process) defines the current effective clearance granted to the subject.  The security label associated with an object defines the classification of the object. (B1 only)

Security Label Implementation

The security label and discretionary group are recorded separately in a labels file indexed by the GID.  The current implementation provides up to 256 levels, 1024 categories, and up to 60,000 discretionary groups, under the constraint that there be no more than a total of 60000 GIDs on any one system. (B1 only)

Security Label Names

Each distinct security label used in the system is given a unique name.  This name is intended for internal use and is distinct from the level and category names used by users to specify labels as a level name optionally followed by a comma separated list of categories.  (See levels(4SX), categories(4SX) and labels(1SX).)  The user friendly name can be arbitrarily long, while the internal security label name is guaranteed to be 14 characters or less. (B1 only)

Device Labels

The label associated with any device is defined by the device’s GID.  Login ports and other single-level assignable devices are restricted to operate within MIN and MAX limits defined in the device clearances database.  (See cleardev(4SX).) (B1 only)

Filesystems are viewed as multi-level devices.  The MAX label for a filesystem is defined to be the label on the special device containing the filesystem.  The MIN label for a filesystem is defined to be the label on the root directory of the filesystem.  All files created within the filesystem are required to be within these limits.  If the special device containing the filesystem is listed in the device clearances database, mount(1SX) will refuse to mount the filesystem unless the filesystem MIN/MAX are bounded by the minimum and maximum recorded in the database. (B1 only)

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 a process ID of 0, 1, and 2 are special processes and are referred to as proc0, proc1, and proc2.

Proc0 is the scheduler.  Proc1 is the initialization process (init). Proc1 is the ancestor of every other process in the system and is used to control the process structure. Proc2 is the page daemon. 

File Descriptor

A file descriptor is a small integer used to do I/O on a file.  The value of a file descriptor is from 0 to 63.  A process may have no more than 64 file descriptors (0-63) open simultaneously.  A file descriptor is returned by system calls such as open(2), or pipe(2).  The file descriptor is used as an argument by calls such as read(2), write(2), ioctl(2), and close(2). 

File Name

Names consisting of 1 to 255 characters may be used to name an ordinary file, special file or directory. 

These characters may be selected from the set of all character values excluding \0 (null) and the ASCII code for / (slash). 

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.  See sh(1).  Although permitted, it is advisable to avoid the use of unprintable characters in file names. 

Path Name and Path Prefix

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. 

More precisely, a path name is a null-terminated character string constructed as follows:

<path-name>::=<file-name>│<path-prefix><file-name>|/
<path-prefix>::=<rtprefix>│/<rtprefix>
<rtprefix>::=<dirname>/│<rtprefix><dirname>/

where <file-name> is a string of 1 to 255 characters other than the ASCII slash and null, and <dirname> is a string of 1 to 255 characters (other than the ASCII slash and null) that names a directory. 
 
The complete path name may be no longer than 1024 characters including ASCII slashes and null. 

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. 

Unless specifically stated otherwise, the null path name is treated as if it named a non-existent file. 

Directory

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.  The root directory of a process need not be the root directory of the root file system. 

Multi-Level (SECURED) Directories

Directories marked with the special privilege "SECURED" function as multi-level directories.  When a path search encounters a multi-level directory, the path is deflected to a subdirectory invisible to the user.  The security label name (see above) associated with the user’s current operating label is inserted in the path.  The path therefore invisibly enters a subdirectory named after the subject’s security label.  When evaluating a path using ".." to enter the multi-level directory, a second ".." is inserted in the path making the multi-level directory invisible from below as well as above.  This allows for the multiplexing of a directory across multiple classification levels.  Because the super-user is exempt from this deflection, the actual directory structure is visible to super-user. (B1 only)

File Access Permissions

Accesses to all objects are controlled by the system in order to implement the security policy.  The policy implemented offers two levels of checks on each object:  mandatory protection and discretionary protection.  Mandatory protection guarantees that labeled objects cannot be accessed directly or indirectly by users not cleared for access to such data by a security administrator.  Discretionary protection allows the owner of an object to further restrict access, for example, to those among cleared personnel who have a "need to know." Discretionary access controls are set at the discretion of the user.  Mandatory access controls are enforced independent of the user except as authorized by trusted programs (e.g. chpriv(1SX).) 

Mandatory Protection (Mandatory Access Control (MAC))

Mandatory read/stat, write/create, and execute/search permissions on a file or read, write, or alter permissions on an IPC object are granted to a process if one of the following are true:

The effective user ID of the process is super-user. 

The access request is for read/stat or execute/search and the clearance of the process (security label specified by the subject’s effective GID) dominates the classification of the object (security label specified by the object’s GID.) 

The access request is for write, create or alter and the clearance of the process (security label specified by the subject’s effective GID) matches exactly the classification of the object (security label specified by the object’s GID.) 

Otherwise, permissions are denied.  (Note: see individual system call descriptions for special cases not covered by this general definition.) (B1 only)

Discretionary Protection (Discretionary Access Control (DAC))

Discretionary read, write, and execute/search permissions on a file are granted to a process if the mandatory checks are passed and one or more of the following are true:

The effective user ID of the process is super-user. 

The effective user ID of the process matches the user ID of the owner of the file and the appropriate access bit of the “owner” portion (0700) of the file mode is set. 

The effective user ID of the process does not match the user ID of the owner of the file, and the discretionary group indirectly referenced by the effective GID of the process matches the discretionary group of the file and the appropriate access bit of the “group” portion (0070) of the file mode is set. 

The effective user ID of the process does not match the user ID of the owner of the file, and the effective discretionary group ID of the process does not match the discretionary group ID of the file, and the appropriate access bit of the “other” portion (0007) of the file mode is set. 

Otherwise, the corresponding permissions are denied.  (Note: see individual system call descriptions for special cases not covered by this general definition.) 

Regions

A region is a contiguous section of virtual memory that may be treated as a single object by the operating system.  Every process created on a CX/UX system will possess a text, data, and stack region at it’s inception.  Additionally a process may attach one or more shared memory regions to it’s virtual address space via the shmat(2) system service.  These shared memory regions may be detached from the processes address space via the shmdt(2) system service.  Test, data and stack regions may be locked into memory (made immune to paging attempts) via the plock(2) system service.  Shared memory regions may be locked into memory via the shmctl(2) system service. 

Message Queue Identifier

A message queue identifier (msqid) is a unique positive integer created by a msgget(2) system call.  Each msqid has a message queue and a data structure associated with it.  The data structure is referred to as msqid_ds and contains the following members:

structipc_perm msg_perm; /∗ operation permission struct ∗/
ushortmsg_cbytes;/∗ current number of bytes on q ∗/
ushortmsg_qnum;/∗ number of msgs on q ∗/
ushortmsg_qbytes;/∗ max number of bytes on q ∗/
pid_tmsg_lspid;/∗ pid of last msgsnd operation ∗/
pid_tmsg_lrpid;/∗ pid of last msgrcv operation ∗/
time_tmsg_stime;/∗ last msgsnd time ∗/
time_tmsg_rtime;/∗ last msgrcv time ∗/
time_tmsg_ctime;/∗ last change time ∗/
/∗ Times measured in secs since ∗/
/∗ 00:00:00 GMT, Jan. 1, 1970 ∗/

Msg_perm is an ipc_perm structure that specifies the message operation permission (see below).  This structure includes the following members:

uid_tcuid;/∗ creator user id ∗/
gid_tcgid;/∗ creator group id ∗/
uid_tuid;/∗ user id ∗/
gid_tgid;/∗ group id ∗/
mode_tmode;/∗ r/w permission ∗/

Msg_cbytes is the current number of bytes on the queue.  Msg_qnum is the number of messages currently on the queue.  Msg_qbytes is the maximum number of bytes allowed on the queue.  Msg_lspid is the process id of the last process that performed a msgsnd operation. Msg_lrpid is the process id of the last process that performed a msgrcv operation. Msg_stime is the time of the last msgsnd operation, msg_rtime is the time of the last msgrcv operation, and msg_ctime is the time of the last msgctl(2) operation that changed a member of the above structure. 

Message Operation Permissions

In the msgop(2) and msgctl(2) system call descriptions, the permission required for an operation is given as "{token}", where "token" is the type of permission needed interpreted as follows:

00400 Read by user

00200 Write by user

00060 Read, Write by group

00006 Read, Write by others

Read and Write permissions on a msqid are granted to a process if the mandatory checks are passed and one or more of the following are true:

The effective user ID of the process is super-user. 

The effective user ID of the process matches msg_perm.[c]uid in the data structure associated with msqid and the appropriate bit of the ”user” portion (0600) of msg_perm.mode is set. 

The effective user ID of the process does not match msg_perm.[c]uid and the effective discretionary group ID of the process matches msg_perm.[c]gid and the appropriate bit of the ”group” portion (060) of msg_perm.mode is set. 

The effective user ID of the process does not match msg_perm.[c]uid and the effective discretionary group ID of the process does not match msg_perm.[c]gid and the appropriate bit of the ”other” portion (06) of msg_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Semaphore Identifier

A semaphore identifier (semid) is a unique positive integer created by a semget(2) system call.  Each semid has a set of semaphores and a data structure associated with it.  The data structure is referred to as semid_ds and contains the following members:

structipc_perm sem_perm; /∗ operation permission struct ∗/
ushortsem_nsems;/∗ number of sems in set ∗/
time_tsem_otime;/∗ last operation time ∗/
time_tsem_ctime;/∗ last change time ∗/
/∗ Times measured in secs since ∗/
o.ft 1/∗ 00:00:00 GMT, Jan. 1, 1970 ∗/

Sem_perm is an ipc_perm structure that specifies the semaphore operation permission (see below).  This structure includes the following members:

uid_tcuid;/∗ creator user id ∗/
gid_tcgid;/∗ creator group id ∗/
uid_tuid;/∗ user id ∗/
gid_tgid;/∗ group id ∗/
mode_tmode;/∗ r/a permission ∗/

The value of sem_nsems is equal to the number of semaphores in the set.  Each semaphore in the set is referenced by a positive integer referred to as a sem_num. Sem_num values run sequentially from 0 to the value of sem_nsems minus 1. Sem_otime is the time of the last semop(2) operation, and sem_ctime is the time of the last semctl(2) operation that changed a member of the above structure. 

A semaphore is a data structure that contains the following members:

ushortsemval;/∗ semaphore value ∗/
pid_tsempid;/∗ pid of last operation  ∗/
ushortsemncnt;/∗ # awaiting semval > cval ∗/
ushortsemzcnt;/∗ # awaiting semval = 0 ∗/

Semval is a non-negative integer.  Sempid is equal to the process ID of the last process that performed a semaphore operation on this semaphore.  Semncnt is a count of the number of processes that are currently suspended awaiting this semaphore’s semval to become greater than its current value.  Semzcnt is a count of the number of processes that are currently suspended awaiting this semaphore’s semval to become zero. 

Semaphore Operation Permissions

In the semop(2) and semctl(2) system call descriptions, the permission required for an operation is given as "{token}", where "token" is the type of permission needed interpreted as follows:

00400 Read by user

00200 Alter by user

00060 Read, Alter by group

00006 Read, Alter by others

Read and Alter permissions on a semid are granted to a process if one or more of the following are true:

The effective user ID of the process is super-user. 

The effective user ID of the process matches sem_perm.[c]uid in the data structure associated with semid and the appropriate bit of the ”user” portion (0600) of sem_perm.mode is set. 

The effective user ID of the process does not match sem_perm.[c]uid and the effective group ID of the process matches sem_perm.[c]gid and the appropriate bit of the ”group” portion (060) of sem_perm.mode is set. 

The effective user ID of the process does not match sem_perm.[c]uid and the effective group ID of the process does not match sem_perm.[c]gid and the appropriate bit of the ”other” portion (06) of sem_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Shared Memory Identifier

A shared memory identifier (shmid) is a unique positive integer created by a shmget(2) system call.  Each shmid has a segment of memory (referred to as a shared memory segment) and a data structure associated with it.  The data structure is referred to as shmid_ds and contains the following members:

structipc_perm shm_perm; /∗ operation permission struct ∗/
intshm_segsz;/∗ size of segment ∗/
structregion ∗shm_reg;/∗ pointer to region structure ∗/
pid_tshm_lpid;/∗ pid of last operation ∗/
pid_tshm_cpid;/∗ creator pid ∗/
shortshm_cnattch;/∗ number of loaded attaches ∗/
shortshm_nattch;/∗ number of current attaches ∗/
time_tshm_atime;/∗ last attach time ∗/
time_tshm_dtime;/∗ last detach time ∗/
time_tshm_ctime;/∗ last change time ∗/
/∗ Times measured in secs since ∗/
/∗ 00:00:00 GMT, Jan. 1, 1970 ∗/

Shm_perm is an ipc_perm structure that specifies the shared memory operation permission (see below).  This structure includes the following members:

uid_tcuid;/∗ creator user id ∗/
gid_tcgid;/∗ creator group id ∗/
uid_tuid;/∗ user id ∗/
gid_tgid;/∗ group id ∗/
mode_tmode;/∗ r/w permission ∗/

Shm_segsz specifies the size of the shared memory segment.  Shm_reg is the address of the region structure associated with this segment.  Shm_cpid is the process id of the process that created the shared memory identifier.  Shm_lpid is the process id of the last process that performed a shmop(2) operation. Shm_cnattch is the number of in-core processes attached to this segment.  Shm_nattch is the number of processes that currently have this segment attached.  Shm_atime is the time of the last shmat operation, shm_dtime is the time of the last shmdt operation, and shm_ctime is the time of the last shmctl(2) operation that changed one of the members of the above structure. 

Shared Memory Operation Permissions

In the shmop(2) and shmctl(2) system call descriptions, the permission required for an operation is given as "{token}", where "token" is the type of permission needed interpreted as follows:

00400 Read by user

00200 Write by user

00060 Read, Write by group

00006 Read, Write by others

Read and Write permissions on a shmid are granted to a process if mandatory checks are passed and one or more of the following are true:

The effective user ID of the process is super-user. 

The effective user ID of the process matches shm_perm.[c]uid in the data structure associated with shmid and the appropriate bit of the ”user” portion (0600) of shm_perm.mode is set. 

The effective user ID of the process does not match shm_perm.[c]uid and the effective discretionary group ID of the process matches shm_perm.[c]gid and the appropriate bit of the ”group” portion (060) of shm_perm.mode is set. 

The effective user ID of the process does not match shm_perm.[c]uid and the effective discretionary group ID of the process does not match shm_perm.[c]gid and the appropriate bit of the ”other” portion (06) of shm_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Frequency Based Scheduler Identifier

A frequency based scheduler identifier (fbsid) is a unique non-negative integer created by a fbsget(2) system call.  Each fbsid (referred to as a frequency based scheduler) has processes to run at a frequency and a data structure associated with it.  The data structure is referred to as fbsid_ds and contains the following members:

structipc_perm fbs_perm; /∗ operation permission struct ∗/
intfbs_flags;/∗ flags word ∗/
intfbs_cycles;/∗ # of minor cycles per frame ∗/
intfbs_cprocs;/∗ max # of processes per cycle ∗/
intfbs_fprocs;/∗ max # of processes on entire FBS ∗/
intfbs_devid;/∗ reserved ∗/
charfbs_dev[MAXPATHLEN];   /∗ pathname of attached device ∗/
intfbs_ccycle;/∗ current minor cycle ∗/
intfbs_cframe;/∗ current major frame ∗/
intfbs_overruns;/∗ total number of overruns ∗/

Fbs_perm is an ipc_perm structure that specifies the freqency based scheduler operation permission (see below).  This structure includes the following members:

uid_tcuid;/∗ creator user id ∗/
gid_tcgid;/∗ creator group id ∗/
uid_tuid;/∗ user id ∗/
gid_tgid;/∗ group id ∗/
mode_tmode;/∗ r/w permission ∗/

Fbs_flags indicates whether the FBS is attached (FBS_ATTACHED) and/or using end-of-cycle scheduling (FBS_EOCINV).  Fbs_cycles is equal to the number of minor cycles per major frame.  Fbs_cprocs is equal to the maximum number of processes that can be scheduled per minor cycle.  Fbs_fprocs is equal to the maximum number of processes that can be scheduled on the FBS.  Fbs_dev contains the pathname of the device being used to control the duration of a minor cycle (if end-of-cycle processing is not being used).  Fbs_ccycle is equal to the current minor cycle and fbs_cframe is equal to the current major frame. Finally, fbs_overruns is equal to the total number of overruns which have occurred since the FBS was last started. 

Frequency Based Scheduler Operation Permissions

In the fbsop(2), fbsctl(2), fbsop(2), pmctl(2), and pmop(2) system call descriptions, the permission required for an operation is given as "{token}", where "token" is the type of permission needed interpreted as follows:

00400 Read by user

00200 Alter by user

00060 Read, Alter by group

00006 Read, Alter by others

Read and Alter permissions on a fbsid are granted to a process if mandatory checks are passed and one or more of the following are true:

The effective user ID of the process is super-user. 

The effective user ID of the process matches fbs_perm.[c]uid in the data structure associated with fbsid and the appropriate bit of the ”user” portion (0600) of fbs_perm.mode is set. 

The effective user ID of the process does not match fbs_perm.[c]uid and the effective discretionary group ID of the process matches fbs_perm.[c]gid and the appropriate bit of the ”group” portion (060) of fbs_perm.mode is set. 

The effective user ID of the process does not match fbs_perm.[c]uid and the effective discretionary group ID of the process does not match fbs_perm.[c]gid and the appropriate bit of the ”other” portion (06) of fbs_perm.mode is set. 

Otherwise, the corresponding permissions are denied. 

Universe

Each process has associated with it a flag -- a character string -- called the current universe.  This flag affects the translation of conditional symbolic links in the file system, changing the process’ view of the directory tree.  A conditional symbolic link is an ordinary symbolic link containing the character sequence ‘{}’.  The braces are replaced by the current universe name at pathname translation time so that, for example, a symbolic link with a value of ‘.{}lib’ becomes ‘.attlib’ in the att universe, and ‘.ucblib’ in the ucb universe. 

There are currently two supported universes: att and ucb, att being the default at login.  The purpose of the universe concept is to achieve a higher degree of compatibility with both the AT&T SYSTEM V and 4 BSD versions of Unix.  The att universe creates a compilation environment that should appear to be AT&T SYSTEM V, and the ucb universe creates a compilation environment that should appear to be 4 BSD.  Shell commands are available for changing one’s universe. 

Physical Memory Spaces

Involved with the capability to map physical memory is the concept of physical memory spaces.  A physical memory space is a contigous section of physical memory that shares the same characteristics.  The current types of physical memory for the CX/UX system are global memory, local memory, and I/O memory.  Global refers to RAM memory globally accessible by all processors on the system.  Local refers to RAM memory readily accessible to only one processor on the system.  On a single processor system all memory is considered to be global.  I/O refers to those memory locations that are used to map the control and data registers of various I/O controllers. 

STREAMS

A set of kernel mechanisms that support the development of network services and data communication drivers.  It defines interface standards for character input/output within the kernel and between the kernel and user level processes.  The STREAMS mechanism is composed of utility routines, kernel facilities and a set of data structures. 

Stream

A stream is a full-duplex data path within the kernel between a user process and driver routines.  The primary components are a stream head, a driver and zero or more modules between the stream head and driver.  A stream is analogous to a Shell pipeline except that data flow and processing are bidirectional. 

Stream Head

In a stream, the stream head is the end of the stream that provides the interface between the stream and a user process.  The principle functions of the stream head are processing STREAMS-related system calls, and passing data and information between a user process and the stream. 

Driver

In a stream, the driver provides the interface between peripheral hardware and the stream.  A driver can also be a pseudo-driver, such as a multiplexor or log driver [see log(7)], which is not associated with a hardware device. 

Module

A module is an entity containing processing routines for input and output data.  It always exists in the middle of a stream, between the stream’s head and a driver.  A module is the STREAMS counterpart to the commands in a Shell pipeline except that a module contains a pair of functions which allow independent bidirectional (downstream and upstream) data flow and processing. 

Downstream

In a stream, the direction from stream head to driver. 

Upstream

In a stream, the direction from driver to stream head. 

Message

In a stream, one or more blocks of data or information, with associated STREAMS control structures.  Messages can be of several defined types, which identify the message contents.  Messages are the only means of transferring data and communicating within a stream. 

Message Queue

In a stream, a linked list of messages awaiting processing by a module or driver. 

Read Queue

In a stream, the message queue in a module or driver containing messages moving upstream. 

Write Queue

In a stream, the message queue in a module or driver containing messages moving downstream. 

Multiplexor

A multiplexor is a driver that allows streams associated with several user processes to be connected to a single driver, or several drivers to be connected to a single user process.  STREAMS does not provide a general multiplexing driver, but does provide the facilities for constructing them, and for connecting multiplexed configurations of streams. 

SEE ALSO

close(2), ioctl(2), open(2), pipe(2), read(2), write(2), universe(1), intro(3). 

CX/UX Programmer’s Reference Manual