1.Dd December 3, 2003       \" DATE 
2.Dt db_deadlock 1       \" Program name and manual section number 
3.Os Darwin
4.Sh NAME                 \" Section Header - required - don't modify 
5.Nm db_deadlock
6.\" The following lines are read in generating the apropos(man -k) database. Use only key
7.\" words here as the database is built based on the words here and in the .ND line. 
8.\" Use .Nm macro to designate other names for the documented program.
9.Sh SYNOPSIS             \" Section Header - required - don't modify
10.Nm
11.Op Fl Vv
12.Op Fl a Ar e | m | n | o | w | y
13.Op Fl h Ar home
14.Op Fl L Ar file
15.Op Fl t Ar sec.usec
16.Sh DESCRIPTION          \" Section Header - required - don't modify
17The
18.Nm
19utility traverses the database environment lock region, and aborts a lock request each time it detects a deadlock or a lock request that has timed out. By default, in the case of a deadlock, a random lock request is chosen to be aborted.
20.Pp
21This utility should be run as a background daemon, or the underlying Berkeley DB deadlock detection interfaces should be called in some other way, whenever there are multiple threads or processes accessing a database and at least one of them is modifying it.
22.Pp
23The options are as follows:
24.Bl -tag -width
25.It Fl a
26When a deadlock is detected, abort the locker:
27.Bl -tag -width
28.It m
29with the greatest number of locks
30.It n
31with the fewest number of locks
32.It o
33with the oldest locker ID
34.It w
35with the fewest number of write locks
36.It y
37with the youngest locker ID
38.El
39.Pp
40When lock or transaction timeouts have been specified:
41.Bl -tag -width
42.It e
43abort any lock request that has timed out
44.El
45.It Fl h
46Specify a home directory for the database environment; by default, the current working directory is used.
47.It Fl L
48Log the execution of the db_deadlock utility to the specified file in the following format, where ### is the process ID, and the date is the time the utility was started.
49.Pp
50.D1 db_deadlock: ### Wed Jun 15 01:23:45 EDT 1995
51.Pp
52This file will be removed if the db_deadlock utility exits gracefully.
53.It Fl t
54Check the database environment every sec seconds plus usec microseconds to see if a process has been forced to wait for a lock; if one has, review the database environment lock structures.
55.It Fl V
56Write the library version number to the standard output, and exit.
57.It Fl v
58Run in verbose mode, generating messages each time the detector runs.
59.El
60.Pp
61If the -t option is not specified, db_deadlock will run once and exit.
62.Pp
63The db_deadlock utility uses a Berkeley DB environment (as described for the -h option, the environment variable DB_HOME, or because the utility was run in a directory containing a Berkeley DB environment). In order to avoid environment corruption when using a Berkeley DB environment, db_deadlock should always be given the chance to detach from the environment and exit gracefully. To cause db_deadlock to release all environment resources and exit cleanly, send it an interrupt signal (SIGINT).
64.Pp
65The db_deadlock utility does not attempt to create the Berkeley DB shared memory regions if they do not already exist. The application which creates the region should be started first, and then, once the region is created, the db_deadlock utility should be started.
66.Pp
67The DB_ENV->lock_detect method is the underlying method used by the db_deadlock utility. See the db_deadlock utility source code for an example of using DB_ENV->lock_detect in a IEEE/ANSI Std 1003.1 (POSIX) environment.
68.Pp
69The 
70.Nm
71utility exits 0 on success, and >0 if an error occurs.
72.Pp
73.Sh ENVIRONMENT      \" May not be needed
74.Bl -tag -width "DB_HOME" \" ENV_VAR_1 is width of the string ENV_VAR_1
75.It Ev DB_HOME
76If the -h option is not specified and the environment variable DB_HOME is set, it is used as the path of the database home, as described in DB_ENV->open.
77.El                      
78.\" .Sh FILES                \" File used or created by the topic of the man page
79.\" .Bl -tag -width "/Users/joeuser/Library/really_long_file_name" -compact
80.\" .It Pa /usr/share/file_name
81.\" FILE_1description
82.\" .It Pa /Users/joeuser/Library/really_long_file_name
83.\" FILE_2 description
84.\" .Sh DIAGNOSTICS       \" May not be needed
85.\" .Bl -diag
86.\" .It Diagnostic Tag
87.\" Diagnostic informtion here.
88.\" .It Diagnostic Tag
89.\" Diagnostic informtion here.
90.\" .El
91.Sh SEE ALSO 
92.Xr db_archive 1 ,
93.Xr db_checkpoint 1 ,
94.Xr db_dump 1 ,
95.Xr db_load 1 ,
96.Xr db_printlog 1 ,
97.Xr db_recover 1 ,
98.Xr db_stat 1 ,
99.Xr db_upgrade 1 ,
100.Xr db_verify 1
101.\" .Sh BUGS              \" Document known, unremedied bugs 
102.\" .Sh HISTORY           \" Document history if command behaves in a unique manner 
103