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)							      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 envi-
       ronment and the ULTRIX operating	system.

Environmental Compatibility
       Some system calls contain System	V and POSIX features that are compati-
       ble 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 sys-
       tem.  For example, a function performed under the ULTRIX	operating sys-
       tem can produce different results in the	System V or POSIX environment.
       If conflicts exist, the ENVIRONMENT section of the reference page high-
       lights 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 pro-
	    gram.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 environ-
	    ment.

	    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 defini-
       tions. 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  oth-
       erwise 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  per-
	    formed 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 exe-
	    cute.  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 per-
	    mission 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	 supe-
		      ruser.

		 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	corre-
		      sponding user ID and group ID of the file, but the  per-
		      missions 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 charac-
	    ters 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	appro-
		      priate 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  permis-
	    sion*/  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  fur-
	    ther  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 sepa-
	    rated 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	 path-
	    name refers	to the current directory.

       Process ID
	    Each active	process	in the system is uniquely identified by	a pos-
	    itive 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 identi-
	    fied 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  cre-
	    ated  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  mem-
	    bers:  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 mem-
	    ber	 is a count of the number of processes that are	currently sus-
	    pended 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	appro-
		      priate 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 consid-
	    ered 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 con-
	    tains  the following members: struct  ipc_perm shm_perm;  /*opera-
	    tion 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 follow-
	    ing	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	appro-
		      priate 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	 reli-
	    able, 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	commu-
	    nications 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 consid-
	    ered 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 spe-
	    cial 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