Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
intro(2)                  FreeBSD 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) service.

       Additionally, some Section 2 reference pages contain an ENVIRONMENT
       section that describes differences between the POSIX or SYSTEM V
       environment 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
       applications 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
       structures 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
            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 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:

                 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 control 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
            accounting facilities.  The positive integer corresponding to this
            group is called the real group ID.

            All processes have a real user ID and real group ID.  These are
            initialized from the equivalent attributes of the parent process.

       Root Directory and Current Working Directory
            Each process has associated with it a concept of a root directory
            and a current working directory for the purpose of resolving path
            name searches.  A process's root directory does not need to be the
            root directory of the root file system.

       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
            members:
            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
            semaphore 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
            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 shm_segz member specifies the size of the shared memory
            segment.  The shm_cpid member is the process ID of the process
            that created 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 members 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 certain format.  An Address Family is the set of addresses for a
            specific group of protocols.  Each socket has an address chosen
            from the address family in which the socket was created.

       Special Processes
            Those processes that have a process ID of 0, 1, and 2 are
            considered special processes.  Process 0 is the scheduler.
            Process 1 is the initialization process init, 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
            grouping 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)

Name | Syntax | Description | Environmental Compatibility | Return Values | Definitions | See Also

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=intro&sektion=2&manpath=ULTRIX+4.2>

home | help