_O_n_l_i_n_e _M_a_n_u_a_l	     Devices and Facilities		  lock(4)



NNNNAAAAMMMMEEEE
     lock - hierarchical lock management

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     The TX lock manager supports two-level hierarchical locking:
     at	the file level and at the block	level.	Each file has a
     set of blocks as its immediate descendants.  Each block has
     a unique file as parent.  The lock	manager	can be invoked
     indirectly	by the _o_p_e_n and	_f_l_o_c_k system calls; see	the sys-
     tem calls in this manual.

     TTTTyyyyppppeeeessss ooooffff AAAAcccccccceeeessssssss
     The interfaces described below are	specific to the	TX
     operating system; there is	some level of compatibility with
     4.2BSD and	with UNIX System V.

     Access to a resource (a file or a single block of a file)
     may be either _e_x_c_l_u_s_i_v_e (X) or _s_h_a_r_e_d (S).	 Exclusive access
     prohibits _a_l_l other access	to the resource; shared	access
     permits other shared access to the	resource and prohibits
     anyone from obtaining exclusive access to the resource.
     Exclusive access is generally used	for writing, and shared
     access for	reading.

     User programs may request either shared or	exclusive access
     to	an entire file using the _f_l_o_c_k system call or with the
     O_SHLOCK or O_EXLOCK options to the _o_p_e_n system call.  The
     4.2BSD release of UNIX uses the arguments LOCK_SH and
     LOCK_EX to	_f_l_o_c_k to request shared	and exclusive file lock-
     ing, respectively.	 Programs which	do not use the _f_l_o_c_k call
     automatically are granted _i_n_t_e_n_t locks to the file	when the
     _o_p_e_n system call is issued:  an _i_n_t_e_n_t _s_h_a_r_e_d (IS)	lock is
     obtained when read-only access is required, and an	_i_n_t_e_n_t
     _e_x_c_l_u_s_i_v_e (IX) lock is obtained when any form of write
     access is required.

     _U_p_g_r_a_d_e_s of file locks are	possible:  a program may open the
     file initially and	obtain either type of intent lock, and
     then issue	the _f_l_o_c_k system call to increase the level of
     the file lock.  For example, if a user program which already
     had a file	open invoked _f_l_o_c_k to obtain _s_h_a_r_e_d access to the
     file, thus	disallowing any	other processes	from updating the
     file, the lock upgrade would occur	as follows: an _i_n_t_e_n_t
     _s_h_a_r_e_d (IS) lock (read-only access) would be upgraded to a
     _s_h_a_r_e_d (S)	lock, and an _i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (IX) lock	(read-
     write access) would be upgraded to	the special lock type
     _s_h_a_r_e_d-_a_n_d-_i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (SIX).

     Whenever a	program	requests a lock	or an upgrade, one of
     four results occurs:

     1.	   The resource	is available, and the upgrade is per-
	   formed immediately.	_f_l_o_c_k returns immediately to the
	   user; the system call (_o_p_e_n,	_r_e_a_d, or _w_r_i_t_e)	completes
	   and returns to the user.

     2.	   The resource	is in use by one or more other processes
	   (see	LLLLoooocccckkkk CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy below).  If the user	requested
	   _n_o_n-_b_l_o_c_k_i_n_g	action,	the process receives an	immediate






	   error return	(EAGAIN).

     3.	   The resource	is in use by one or more other processes
	   and the user	did _n_o_t	request	non-blocking action.  The
	   lock-management system determines whether the process
	   can be safely blocked.  If so, the process is blocked
	   until the resource is available.

     4.	   The resource	is in use by one or more other processes,
	   the caller did not request non-blocking action, and
	   the system detects that the _d_e_a_d_l_o_c_k	condition would
	   result from blocking	the process.  If the system call
	   causing the deadlock	specifies IO_NOSIGABORT, the
	   error EDEADLOCK is returned to the caller.  If
	   IO_NOSIGABORT is not	specified, the SIGABORT	signal is
	   delivered to	the process with the _c_o_d_e value
	   TR_DEADLOCK.	 If no signal handler is present, the
	   default action is to	kill the process.

     RRRReeeelllleeeeaaaassssiiiinnnngggg aaaa LLLLoooocccckkkk
     Regarding releasing locks,	processes which	are in transac-
     tion state	behave differently from	processes that are not.

     Non-transaction processes may acquire file-level locks.
     Such locks	are released either when the file is _c_l_o_s_ed or
     when the _f_l_o_c_k system call	is invoked with	the unlock
     (LOCK_UN) operation.  Each	file-level lock	is associated
     with a particular file (actually the _i-_n_o_d_e) and a	process.
     (A	file is	not usually _c_l_o_s_ed unless this is the last refer-
     ence by the calling process.)

     Non-transaction processes can also	acquire	block-level locks
     with the _m_b_l_o_c_k system call.  This	call is	allowed	only on
     un-controlled (non-transaction-oriented) files.

     Programs that operate in transaction state	may acquire both
     file-level	and block-level	locks.	File-level locks acquired
     either _b_e_f_o_r_e the beginning of a transaction (or inside a
     transaction) are retained to the end of the transaction even
     if	the program releases them during the transaction.  For
     example, if a program _o_p_e_ns a file	for exclusive access,
     begins a transaction via _t_r_a_n_s (TR_BEGIN, 0), and then,
     while in the transaction, _c_l_o_s_es the file,	the lock will not
     be	released until the transaction commits or aborts.

     BBBBlllloooocccckkkk----LLLLeeeevvvveeeellll LLLLoooocccckkkkiiiinnnngggg
     When a program is using a file that was opened in _c_o_n_t_r_o_l_l_e_d
     (transaction) mode	and in one of the intent-locking modes,
     individual	block-level locks are automatically set	for each
     data page.

     Block-level locks may be set on un-controlled files using
     the _m_b_l_o_c_k	system call.

     Only two forms of block-level lock	exist: a _s_h_a_r_e_d	(S) lock
     on	the page is obtained when a program _r_e_a_ds a page, and an
     _e_x_c_l_u_s_i_v_e (X) lock	on the page is obtained	when a program
     _w_r_i_t_es a page.  An	_e_x_c_l_u_s_i_v_e (X) lock may also be obtained
     by	doing a	``read with lock'' (IO_WINTENT)	operation.  The
     _e_x_c_l_u_s_i_v_e (X) lock, when granted, may actually be an upgrade






     of	an already-existing shared lock.

     MMMMuuuullllttttiiiipppprrrroooocccceeeessssssss TTTTrrrraaaannnnssssaaaaccccttttiiiioooonnnn LLLLoooocccckkkkiiiinnnngggg
     Where multiple processes are involved in the same transac-
     tion via an MXIPC channel,	file and block-level locks are
     assigned on a per transaction basis, rather than per pro-
     cess.  These locks	restrict access	by processes not involved
     in	this transaction, but do not restrict processes	within
     the transaction.  The server process is therefore not locked
     out of a file because the client process has a lock.  To
     maintain data integrity, however, the client process is not
     allowed access to controlled files	while a	server process
     has joined	the transaction.  The client can access	the file
     again when	the server has completed its part of the transac-
     tion.

     LLLLoooocccckkkk MMMMooooddddeeeessss

     The following lock	modes are used within the TX operating
     system:

     #define   LOCK_X		   0xc0	/* exclusive access */
     #define   LOCK_H		   0xc1	/* hold	access -- block	level only */
     #define   LOCK_S		   0xc2	/* share access	*/
     #define   LOCK_IX		   0xc3	/* intention exclusive access */
     #define   LOCK_IS		   0xc4	/* intention share access */
     #define   LOCK_SIX	      0xc5 /* share & intention	exclusive access */
     #define   LOCK_NULL      0xc6 /* no request to access */

     _i_n_t_e_n_t _s_h_a_r_e_d (IS)	and _i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (IX) modes	are
     allowed at	the file level only.  The lock modes have the
     following characteristics:

     _i_n_t_e_n_t _s_h_a_r_e_d (IS)
	      Provides the weakest non-null form of access.  IS
	      implies less access privilege than _i_n_t_e_n_t	_e_x_c_l_u_s_i_v_e
	      (IX) or _s_h_a_r_e_d (S) modes and allows shared (S)
	      locks to be set at the block level for reading.

     _i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (IX)
	      Allows _s_h_a_r_e_d (S)	and _e_x_c_l_u_s_i_v_e (X) locks	to be set
	      at the block level for reading and writing, respec-
	      tively.

     _s_h_a_r_e_d (S)
	      If set at	the file level,	allows read-only access
	      to all descendant	blocks without further locking.

     _h_o_l_d (H) Effective	only at	the block level, is like a _s_h_a_r_e_d
	      (S) lock except incompatible with	itself.	 But will
	      permit another process to	hold a _s_h_a_r_e_d (s) lock on
	      the same block.  This option can be used to reduce
	      dealocking but also reduces concurrency.

     _s_h_a_r_e_d-_a_n_d-_i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (SIX)
	      Combines the privileges of _s_h_a_r_e_d	(S) and	of _i_n_t_e_n_t
	      _e_x_c_l_u_s_i_v_e	(IX) mode.

     _e_x_c_l_u_s_i_v_e (X)
	      Provides the most	restricted access.  If set at the






	      file level, allows reads and writes to all descen-
	      dant blocks with no additional locking.

	  PPPPaaaarrrrttttiiiiaaaallll OOOOrrrrddddeeeerrrriiiinnnngggg ooooffff LLLLoooocccckkkk MMMMooooddddeeeessss bbbbyyyy PPPPrrrriiiivvvviiiilllleeeeggggeeeessss

			 _m_o_s_t _p_r_i_v_i_l_e_g_e_d

				  X
				  |
				 SIX
				  |
			      +-------+
		      S			      IX
			      +-------+
				  |
				  IS
				  |
				 NULL

			_l_e_a_s_t _p_r_i_v_i_l_e_g_e_d

     The lock modes can	be ranked in a partial order by
     privilege,	as shown above.	 Note that it is not a complete
     ordering since IX and S are incomparable.

     FFFFiiiilllleeee----LLLLeeeevvvveeeellll	LLLLoooocccckkkkiiiinnnngggg
     At	the file level,	locking	is of two types: automatic lock-
     ing and manual locking.  Automatic	locks (IS and IX) are set
     at	file _o_p_e_n time.	 An _i_n_t_e_n_t _s_h_a_r_e_d (IS) lock is set for a
     file opened with the O_RDONLY (read only) flag.  An _i_n_t_e_n_t
     _e_x_c_l_u_s_i_v_e (IX) lock is set	for a file opened with O_WRONLY
     (write only), O_RDWR (read/write),	O_APPEND (append),
     O_CREAT (create) or O_TRUNC (truncate to zero) flags.
     Manual locks (S and X) may	be set at file _o_p_e_n time using
     the O_SHLOCK and O_EXLOCK options;	they may also be set
     after the file is opened via the _f_l_o_c_k system call.  A
     _s_h_a_r_e_d (S)	lock is	set using the LOCK_SH operation; LOCK_EX
     sets an _e_x_c_l_u_s_i_v_e (X) lock.

     LLLLoooocccckkkk CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy
     Two locks are _c_o_m_p_a_t_i_b_l_e if they are allowed simultaneously
     on	a given	resource.  If a	lock of	type _x exists, and a user
     requests a	lock of	type _y,	the system checks the compatibil-
     ity of _x and _y.  If they are compatible, the lock is
     granted; otherwise, the requestor is blocked.  (The user
     process may or may	not be blocked depending on whether non-
     blocking I/O was specified	and whether a potential	deadlock
     is	detected.)

     The following tables define the compatibility checking per-
     formed by TX:

     FFFFiiiilllleeee LLLLeeeevvvveeeellll	CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy....	This table describes the compati-
     bility of the request modes at file level,	where NULL
     represents	the absence of a request.  This	table is sym-
     metric:  one side is the current file-lock	state and the
     other side	is the requested new state.  Note that _i_n_t_e_n_t
     _s_h_a_r_e_d (IS) and _i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (IX) locks are compatible;








     but _s_h_a_r_e_d	(S) and	_i_n_t_e_n_t _e_x_c_l_u_s_i_v_e (IX) locks are	not.

		 MMMMooooddddeeee	NULL   IS   IX	 S   SIX   X
		 ___________________________________
		 NULL	 x     x    x	 x    x	   x
		  IS	 x     x    x	 x    x
		  IX	 x     x    x
		  S	 x     x	 x
		 SIX	 x     x
		  X	 x

		     |
		     |
		     |
		     |
		     |
		     |
		     |
		     |








     BBBBlllloooocccckkkk LLLLeeeevvvveeeellll CCCCoooommmmppppaaaattttiiiibbbbiiiilllliiiittttyyyy....	 This table describes the compa-
     tibility of the request modes at block level.  This table is
     symmetric:	 one side is the current block-lock state and the
     other side	is the requested new state.

		       MMMMooooddddeeee   NULL   S	 H   X
		       _______________________
		       NULL    x     x	 x   x
			S      x     x	 x
			H      x     x
			X      x

			   |
			   |
			   |
			   |
			   |
			   |






     This table	defines	the resulting (new) lock mode of a file
     given a requested lock mode and the current combined lock
     mode.  This table is symmetric.

			 LLLLoooocccckkkk MMMMooooddddeeee CCCCoooonnnnvvvveeeerrrrssssiiiioooonnnn
		   MMMMooooddddeeee	  IS	IX     S    SIX	  X
		   ________________________________
		    IS	  IS	IX     S    SIX	  X
		    IX	  IX	IX    SIX   SIX	  X
		    S	   S	SIX    S    SIX	  X
		   SIX	  SIX	SIX   SIX   SIX	  X
		    X	   X	 X     X     X	  X

		       |
		       |
		       |
		       |
		       |
		       |
		       |







     NNNNoooonnnn----TTTTrrrraaaannnnssssaaaaccccttttiiiioooonnnn LLLLoooocccckkkkiiiinnnngggg
     Using locks outside of transactions requires that processes
     co-operate.  For example, if 2 processes open the same file
     with the O_RDWR flag (which sets only the IX lock)	then, the
     processes must ensure data	integrity through co-operation,
     if	both processes write to	the file.  TX cannot guarantee
     data integrity in such a case.)

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     System Calls (2):	close, flock, mblock, open, trans

December 1990				TX Programmer's	Reference