Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

intro(2) [ultrix man page]

intro(2)							System Calls Manual							  intro(2)

Name
       intro - introduction to system calls

Syntax
       #include <errno.h>

Description
       Section	2  describes  the  ULTRIX  system  calls, which are the entries into the ULTRIX kernel.  In this section, reference pages with the
       extension 2yp are specific to the Yellow Pages (YP) service.  Those pages ending in 2nfs are specific to the Network File System (NFS) ser-
       vice.

       Additionally,  some Section 2 reference pages contain an ENVIRONMENT section that describes differences between the POSIX or SYSTEM V envi-
       ronment and the ULTRIX operating system.

Environmental Compatibility
       Some system calls contain System V and POSIX features that are compatible with ULTRIX programs.	These features are provided  for  applica-
       tions  that  are  being ported from System V or POSIX.  Occasionally, the System V and POSIX features conflict with features present in the
       ULTRIX system.  For example, a function performed under the ULTRIX operating system can produce different results in the System V or  POSIX
       environment.  If conflicts exist, the ENVIRONMENT section of the reference page highlights these differences.

       Neither	the  System  V compatibility features nor the POSIX compatibility features are not contained in the standard C runtime library. To
       use the compatibility features, you must set your programming environment to System V or POSIX when you compile or link your programs.	To
       set the System V or POSIX environment, do either of the following:

       1.   Use  the -Y option for the command. For example, the following demonstrates compiling a program in the System V environment first, and
	    then in the POSIX environment:
	    % cc -YSYSTEM_FIVE program.c
	    % cc -YPOSIX program.c

       2.   Globally set the environment variable PROG_ENV to SYSTEM_FIVE or to POSIX.

	    If you are using the C shell, execute the following line or include it in your file:
	    setenv PROG_ENV SYSTEM_FIVE
	    Replace ``SYSTEM_FIVE'' with ``POSIX'' if you are using the POSIX environment.

	    If you are using the Bourne or the System V shell, execute the following line or include it in your file:
	    PROG_ENV=POSIX ; export PROG_ENV
	    Replace ``POSIX'' with ``SYSTEM_FIVE'' if you are using the System V environment.

       In each instance, the command defines a preprocessor symbol, either SYSTEM_FIVE or POSIX.  When the SYSTEM_FIVE symbol is  defined,  the  C
       preprocessor,  selects the System V data structures and symbol definitions. When the POSIX symbol is defined, selects the POSIX data struc-
       tures and symbol definitions.

       In addition, if invokes the linker, it resolves references to routines by searching the System V version of the Standard C library ( )	or
       the  POSIX version of the Standard C library ( ) before it searches The linker searches when the SYSTEM_FIVE symbol is defined. It searches
       when POSIX is defined.

       In the System V environment, if you specify the -lm option on either the or the command	line,  the  linker  includes  the  System  V  math
       library, instead of the ULTRIX math library, in your program.

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.  When a function returns an error condition, it also stores an error number in the  external  variable  This  variable  is  not
       cleared on successful calls.  Thus, you should test only after an error has occurred.

       All return codes and values from functions are of type int unless otherwise noted.

       For a list of the errors and their names as given in <errno.h>, see the reference page.

Definitions
       The following terms are used in Section 2:

       Descriptor
	    An	integer  assigned by the system when a file is referenced by or a socket is referenced by or 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 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

	    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 per-
	    form 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 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 call-
	    er.

	    Read, write, and execute/search permissions on a file are granted to a process in the following instances:

		 o    The process's effective user ID is that of the superuser.

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

		 o    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.

		 o    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:

		 o    If the process is trying to execute an image and the file system is mounted no execute, execute permission is denied.

		 o    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.

		 o    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.

       File Name
	    Names consisting of up to {FILENAME_MAX} characters can be used to name an ordinary file, special file, or directory.

	    These characters can be selected from the set of all ASCII characters excluding null (0) and the ASCII code  for  backslash  (.   The
	    parity bit (bit 8) must be 0.

	    Avoid using asterisks (*), question marks (?), or brackets ([ ]) as part of filenames because of the special meaning attached to these
	    characters by the shell.

       Message Operation Permissions
	    In the and system call descriptions, the permission required for an operation is specified by a token. The token argument is the  type
	    of permission needed and it is 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 are granted to a process if one or more of the following are true:

		 o    The effective user ID of the process is superuser.

		 o    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.

		 o    The effective user ID of the process does not match msg_perm.[c]uid, but the effective  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.

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

	    If none of the previous conditions are true, the read and write permissions are denied.

       Message Queue Identifier
	    A message queue identifier (msqid) is a unique positive integer created by a 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:
	    struct  ipc_perm msg_perm; /*operation permission struct*/
	    ushort  msg_qnum;	       /*number of msgs on q*/
	    ushort  msg_qbytes;        /*max number of bytes on q*/
	    ushort  msg_lspid;	       /*pid of last msgsnd operation*/
	    ushort  msg_lrpid;	       /*pid of last msgrcv operation*/
	    time_t  msg_stime;	       /*last msgsnd time*/
	    time_t  msg_rtime;	       /*last msgrcv time*/
	    time_t  msg_ctime;	       /*last change time*/
				       /*Times measured in secs since*/
				       /*00:00:00 GMT, Jan.1, 1970*/
	    The  msg_perm structure is an ipc_perm structure that specifies the message operation permission.  The msg_perm structure includes the
	    following members:
	    ushort  cuid;     /*creator user id*/
	    ushort  cgid;     /*creator group id*/
	    ushort  uid;      /*user id*/
	    ushort  gid;      /*group id*/
	    ushort  mode;     /*r/w permission*/
	    The msg_qnum member is the number of message currently on the queue.  The msg_qbytes member is the maximum number of bytes allowed	on
	    the  queue.   The  msg_lspid  member  is  the  process ID of the last process that performed a operation.  The msg_lrpid member is the
	    process ID of the last process that performed a operation.	The msg_stime member is the time of the last operation, msg_rtime  is  the
	    time of the last operation, and msg_ctime is the time of the last operation that changed a member of the above structure.

       Parent process ID
	    A  new  process  is  created  by  a  currently active process.  For further information, see The parent process ID of a process is the
	    process ID of its creator.

       Pathname
	    A pathname is a null-terminated character string containing an optional slash (/), followed by zero or more directory names  separated
	    by	slashes.   This  sequence can optionally be followed by another slash and a filename.  The total length of a pathname must be less
	    than {PATHNAME_MAX} characters.

	    If a pathname begins with a slash, the path search begins at the directory.  Otherwise, the search begins  from  the  current  working
	    directory.	A slash by itself names the directory.	A null pathname refers to the current directory.

       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 and the job con-
	    trol mechanisms described in

       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  account-
	    ing 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.

       Semaphore Identifier

	    A semaphore identifier (semid) is a unique positive integer created by a 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:
	    struct  ipc_perm sem_perm; /*operation permission struct*/
	    ushort  sem_nsems;	       /*number of sems in set */
	    time_t  sem_otime;	       /*last operation time*/
	    time_t  sem_ctime;	       /*last change time*/
				       /*Times measured in secs since*/
				       /*00:00:00 GMT, Jan. 1, 1970*/
	    The  sem_perm  is an ipc_perm structure that specifies the semaphore operation permission.	This structure includes the following mem-
	    bers:
	    ushort cuid;  /*creator user id*/
	    ushort cgid;  /*creator group id*/
	    ushort uid;   /*user id*/
	    ushort gid;   /*group id*/
	    ushort mode;  /*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.	The sem_num values run sequentially from 0 to the value of sem_nsems minus 1.  The sem_otime member is the
	    time of the last operation, and sem_ctime is the time of the last operation that changed a member of the above structure.

	    A semaphore is a data structure that contains the following members:
	    ushort  semval;  /*semaphore value*/
	    short   sempid;  /*pid of last operation*/
	    ushort  semncnt; /*# awaiting semval > cval*/
	    ushort  semzcnt; /*# awaiting semval = 0*/
	    The semval member is a non-negative integer.  The sempid member is equal to the process ID of the last process that performed a  sema-
	    phore  operation  on  this	semaphore.  The semncnt member is a count of the number of processes that are currently suspended awaiting
	    this semaphore's semval to become greater than its current value.  The semzcnt member 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 and system call descriptions, the permission required for an operation is specified as {token}.  The token argument is the type
	    of permission needed and it is 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:

		 o    The effective user ID of the process is superuser.

		 o    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.

		 o    The  effective  user  ID	of  the  process does not match sem_perm.[c]uid, but 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.

		 o    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, but the appropriate bit of the other portion (06) of sem_perm.mode is set.

	    If none of the previous conditions are true, the read and alter permissions are denied.

       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.

       Shared Memory Identifier

	    A shared memory identifier (shmid) is a unique positive integer created by a  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 and contains
	    the following members:
	    struct  ipc_perm shm_perm;	/*operation permission struct*/
	    int     shm_segsz;		/*size of segment*/
	    ushort  shm_cpid;		/*creator pid*/
	    ushort  shm_lpid;		/*pid of last operation*/
	    short   shm_nattch; 	/*number of current attaches*/
	    time_t  shm_atime;		/*last attach time*/
	    time_t  shm_dtime;		/*last detach time*/
	    time_t  shm_ctime;		/*last change time*/
					/*Times measured in secs since*/
					/*00:00:00 GMT, Jan. 1, 1970*/
	    The shm_perm member is an ipc_perm structure that specifies the shared memory operation permission.  This structure includes the  fol-
	    lowing members:
	    ushort  cuid;  /*creator user id*/
	    ushort  cgid;  /*creator group id*/
	    ushort  uid;   /*user id*/
	    ushort  gid;   /*group id*/
	    ushort  mode;  /*r/w permission*/
	    The  shm_segz  member specifies the size of the shared memory segment.  The shm_cpid member is the process ID of the process that cre-
	    ated the shared memory identifier.	The shm_lpid member is the process ID of  the  last  process  that  performed  a  operation.   The
	    shm_nattch	member is the number of processes that currently have this segment attached.  The shm_atime member is the time of the last
	    operation, shm_dtime is the time of the last operation, and shm_ctime is the time of the last operation that changed one of  the  mem-
	    bers of the above structure.

       Shared Memory Operation Permissions

	    In	the and system call descriptions, the permission required for an operation is given as {token}.  The token argument is the type of
	    permission needed and it is 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 one or more of the following are true:

		 o    The effective user ID of the process is superuser.

		 o    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.

		 o    The  effective  user  ID	of  the  process does not match shm_perm.[c]uid, but the effective 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.

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

	    If none of the previous conditions are true, the read and write permissions are denied.

       Sockets and Address Families

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

	    Sockets  are  typed  according to their communications properties.	These properties 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 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 cer-
	    tain 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, and is the ancestor of every other process in the system.  It controls the process structure.	Process  2
	    is the paging daemon.

       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 group-
	    ing is used to arbitrate between multiple jobs contending for the same terminal.  For more information, see and

See Also
       cc(1), csh(1), tty(4), intro(3), perror(3)

																	  intro(2)
Man Page