technical/api-lockfile.html - external/gitster/git-htmldocs - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
 <meta name="generator" content="AsciiDoc 8.2.5" />
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
 /*
  border: 1px solid red;
 */
 }

 body {
  margin: 1em 5% 1em 5%;
 }

 a {
  color: blue;
  text-decoration: underline;
 }
 a:visited {
  color: fuchsia;
 }

 em {
  font-style: italic;
 }

 strong {
  font-weight: bold;
 }

 tt {
  color: navy;
 }

 h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
 }

 h1, h2, h3 {
  border-bottom: 2px solid silver;
 }
 h2 {
  padding-top: 0.5em;
 }
 h3 {
  float: left;
 }
 h3 + * {
  clear: left;
 }

 div.sectionbody {
  font-family: serif;
  margin-left: 0;
 }

 hr {
  border: 1px solid silver;
 }

 p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
 }
 span#email {
 }
 span#revision {
  font-family: sans-serif;
 }

 div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
 }
 div#footer-text {
  float: left;
  padding-bottom: 0.5em;
 }
 div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
 }

 div#preamble,
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-right: 10%;
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
 }
 div.title + * {
  margin-top: 0;
 }

 td div.title:first-child {
  margin-top: 0.0em;
 }
 div.content div.title:first-child {
  margin-top: 0.0em;
 }
 div.content + div.title {
  margin-top: 0.0em;
 }

 div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }

 div.listingblock {
  margin-right: 0%;
 }
 div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock > div.content {
  padding-left: 2.0em;
 }

 div.attribution {
  text-align: right;
 }
 div.verseblock + div.attribution {
  text-align: left;
 }

 div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
 }
 div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
 }

 div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
 }

 div.verseblock div.content {
  white-space: pre;
 }

 div.imageblock div.content { padding-left: 0; }
 div.imageblock img { border: 1px solid silver; }
 span.image img { border-style: none; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: italic;
 }
 dd > *:first-child {
  margin-top: 0;
 }

 ul, ol {
  list-style-position: outside;
 }
 div.olist2 ol {
  list-style-type: lower-alpha;
 }

 div.tableblock > table {
  border: 3px solid #527bbd;
 }
 thead {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }

 div.hlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 div.hlist td {
  padding-bottom: 5px;
 }
 td.hlist1 {
  vertical-align: top;
  font-style: italic;
  padding-right: 0.8em;
 }
 td.hlist2 {
  vertical-align: top;
 }

 @media print {
  div#footer-badges { display: none; }
 }

 div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
 }

 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
 }
 div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
 }
 div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
 }
 div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
 }
 /* Workarounds for IE6's broken and incomplete CSS2. */

 div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
 }
 div.sidebar-title, div.image-title {
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
 }

 div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock-content {
  padding-left: 2.0em;
 }

 div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
 }

 /* IE6 sets dynamically generated links as visited. */
 div#toc a:visited { color: blue; }
 </style>
 <title>lockfile API</title>
 </head>
 <body>
 <div id="header">
 <h1>lockfile API</h1>
 </div>
 <div id="preamble">
 <div class="sectionbody">
 <div class="para"><p>The lockfile API serves two purposes:</p></div>
 <div class="ilist"><ul>
 <li>
 <p>
 Mutual exclusion. When we write out a new index file, first
  we create a new file <tt>$GIT_DIR/index.lock</tt>, write the new
  contents into it, and rename it to the final destination
  <tt>$GIT_DIR/index</tt>. We try to create the <tt>$GIT_DIR/index.lock</tt>
  file with O_EXCL so that we can notice and fail when somebody
  else is already trying to update the index file.
 </p>
 </li>
 <li>
 <p>
 Automatic cruft removal. After we create the "lock" file, we
  may decide to <tt>die()</tt>, and we would want to make sure that we
  remove the file that has not been committed to its final
  destination. This is done by remembering the lockfiles we
  created in a linked list and cleaning them up from an
  <tt>atexit(3)</tt> handler. Outstanding lockfiles are also removed
  when the program dies on a signal.
 </p>
 </li>
 </ul></div>
 </div>
 </div>
 <h2 id="_the_functions">The functions</h2>
 <div class="sectionbody">
 <div class="vlist"><dl>
 <dt>
 hold_lock_file_for_update
 </dt>
 <dd>
 <p>
  Take a pointer to <tt>struct lock_file</tt>, the filename of
  the final destination (e.g. <tt>$GIT_DIR/index</tt>) and a flag
  <tt>die_on_error</tt>. Attempt to create a lockfile for the
  destination and return the file descriptor for writing
  to the file. If <tt>die_on_error</tt> flag is true, it dies if
  a lock is already taken for the file; otherwise it
  returns a negative integer to the caller on failure.
 </p>
 </dd>
 <dt>
 commit_lock_file
 </dt>
 <dd>
 <p>
  Take a pointer to the <tt>struct lock_file</tt> initialized
  with an earlier call to <tt>hold_lock_file_for_update()</tt>,
  close the file descriptor and rename the lockfile to its
  final destination. Returns 0 upon success, a negative
  value on failure to close(2) or rename(2).
 </p>
 </dd>
 <dt>
 rollback_lock_file
 </dt>
 <dd>
 <p>
  Take a pointer to the <tt>struct lock_file</tt> initialized
  with an earlier call to <tt>hold_lock_file_for_update()</tt>,
  close the file descriptor and remove the lockfile.
 </p>
 </dd>
 <dt>
 close_lock_file
 </dt>
 <dd>
 <p>
  Take a pointer to the <tt>struct lock_file</tt> initialized
  with an earlier call to <tt>hold_lock_file_for_update()</tt>,
  and close the file descriptor. Returns 0 upon success,
  a negative value on failure to close(2).
 </p>
 </dd>
 </dl></div>
 <div class="para"><p>Because the structure is used in an <tt>atexit(3)</tt> handler, its
 storage has to stay throughout the life of the program. It
 cannot be an auto variable allocated on the stack.</p></div>
 <div class="para"><p>Call <tt>commit_lock_file()</tt> or <tt>rollback_lock_file()</tt> when you are
 done writing to the file descriptor. If you do not call either
 and simply <tt>exit(3)</tt> from the program, an <tt>atexit(3)</tt> handler
 will close and remove the lockfile.</p></div>
 <div class="para"><p>If you need to close the file descriptor you obtained from
 <tt>hold_lock_file_for_update</tt> function yourself, do so by calling
 <tt>close_lock_file()</tt>. You should never call <tt>close(2)</tt> yourself!
 Otherwise the <tt>struct
 lock_file</tt> structure still remembers that the file descriptor
 needs to be closed, and a later call to <tt>commit_lock_file()</tt> or
 <tt>rollback_lock_file()</tt> will result in duplicate calls to
 <tt>close(2)</tt>. Worse yet, if you <tt>close(2)</tt>, open another file
 descriptor for completely different purpose, and then call
 <tt>commit_lock_file()</tt> or <tt>rollback_lock_file()</tt>, they may close
 that unrelated file descriptor.</p></div>
 </div>
 <div id="footer">
 <div id="footer-text">
 Last updated 2009-02-14 08:18:54 UTC
 </div>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
	"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<meta name="generator" content="AsciiDoc 8.2.5" />
	<style type="text/css">
	/* Debug borders */
	p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
	/*
	border: 1px solid red;
	*/
	}

	body {
	margin: 1em 5% 1em 5%;
	}

	a {
	color: blue;
	text-decoration: underline;
	}
	a:visited {
	color: fuchsia;
	}

	em {
	font-style: italic;
	}

	strong {
	font-weight: bold;
	}

	tt {
	color: navy;
	}

	h1, h2, h3, h4, h5, h6 {
	color: #527bbd;
	font-family: sans-serif;
	margin-top: 1.2em;
	margin-bottom: 0.5em;
	line-height: 1.3;
	}

	h1, h2, h3 {
	border-bottom: 2px solid silver;
	}
	h2 {
	padding-top: 0.5em;
	}
	h3 {
	float: left;
	}
	h3 + * {
	clear: left;
	}

	div.sectionbody {
	font-family: serif;
	margin-left: 0;
	}

	hr {
	border: 1px solid silver;
	}

	p {
	margin-top: 0.5em;
	margin-bottom: 0.5em;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.1em;
	}
	span#email {
	}
	span#revision {
	font-family: sans-serif;
	}

	div#footer {
	font-family: sans-serif;
	font-size: small;
	border-top: 2px solid silver;
	padding-top: 0.5em;
	margin-top: 4.0em;
	}
	div#footer-text {
	float: left;
	padding-bottom: 0.5em;
	}
	div#footer-badges {
	float: right;
	padding-bottom: 0.5em;
	}

	div#preamble,
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-right: 10%;
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.5em;
	margin-bottom: 2.5em;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	font-family: sans-serif;
	font-weight: bold;
	text-align: left;
	margin-top: 1.0em;
	margin-bottom: 0.5em;
	}
	div.title + * {
	margin-top: 0;
	}

	td div.title:first-child {
	margin-top: 0.0em;
	}
	div.content div.title:first-child {
	margin-top: 0.0em;
	}
	div.content + div.title {
	margin-top: 0.0em;
	}

	div.sidebarblock > div.content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}

	div.listingblock {
	margin-right: 0%;
	}
	div.listingblock > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock > div.content {
	padding-left: 2.0em;
	}

	div.attribution {
	text-align: right;
	}
	div.verseblock + div.attribution {
	text-align: left;
	}

	div.admonitionblock .icon {
	vertical-align: top;
	font-size: 1.1em;
	font-weight: bold;
	text-decoration: underline;
	color: #527bbd;
	padding-right: 0.5em;
	}
	div.admonitionblock td.content {
	padding-left: 0.5em;
	border-left: 2px solid silver;
	}

	div.exampleblock > div.content {
	border-left: 2px solid silver;
	padding: 0.5em;
	}

	div.verseblock div.content {
	white-space: pre;
	}

	div.imageblock div.content { padding-left: 0; }
	div.imageblock img { border: 1px solid silver; }
	span.image img { border-style: none; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: italic;
	}
	dd > *:first-child {
	margin-top: 0;
	}

	ul, ol {
	list-style-position: outside;
	}
	div.olist2 ol {
	list-style-type: lower-alpha;
	}

	div.tableblock > table {
	border: 3px solid #527bbd;
	}
	thead {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}

	div.hlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	div.hlist td {
	padding-bottom: 5px;
	}
	td.hlist1 {
	vertical-align: top;
	font-style: italic;
	padding-right: 0.8em;
	}
	td.hlist2 {
	vertical-align: top;
	}

	@media print {
	div#footer-badges { display: none; }
	}

	div#toctitle {
	color: #527bbd;
	font-family: sans-serif;
	font-size: 1.1em;
	font-weight: bold;
	margin-top: 1.0em;
	margin-bottom: 0.1em;
	}

	div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
	margin-top: 0;
	margin-bottom: 0;
	}
	div.toclevel2 {
	margin-left: 2em;
	font-size: 0.9em;
	}
	div.toclevel3 {
	margin-left: 4em;
	font-size: 0.9em;
	}
	div.toclevel4 {
	margin-left: 6em;
	font-size: 0.9em;
	}
	/* Workarounds for IE6's broken and incomplete CSS2. */

	div.sidebar-content {
	background: #ffffee;
	border: 1px solid silver;
	padding: 0.5em;
	}
	div.sidebar-title, div.image-title {
	font-family: sans-serif;
	font-weight: bold;
	margin-top: 0.0em;
	margin-bottom: 0.5em;
	}

	div.listingblock div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock-content {
	padding-left: 2.0em;
	}

	div.exampleblock-content {
	border-left: 2px solid silver;
	padding-left: 0.5em;
	}

	/* IE6 sets dynamically generated links as visited. */
	div#toc a:visited { color: blue; }
	</style>
	<title>lockfile API</title>
	</head>
	<body>
	<div id="header">
	<h1>lockfile API</h1>
	</div>
	<div id="preamble">
	<div class="sectionbody">
	<div class="para"><p>The lockfile API serves two purposes:</p></div>
	<div class="ilist"><ul>
	<li>
	<p>
	Mutual exclusion. When we write out a new index file, first
	we create a new file <tt>$GIT_DIR/index.lock</tt>, write the new
	contents into it, and rename it to the final destination
	<tt>$GIT_DIR/index</tt>. We try to create the <tt>$GIT_DIR/index.lock</tt>
	file with O_EXCL so that we can notice and fail when somebody
	else is already trying to update the index file.
	</p>
	</li>
	<li>
	<p>
	Automatic cruft removal. After we create the "lock" file, we
	may decide to <tt>die()</tt>, and we would want to make sure that we
	remove the file that has not been committed to its final
	destination. This is done by remembering the lockfiles we
	created in a linked list and cleaning them up from an
	<tt>atexit(3)</tt> handler. Outstanding lockfiles are also removed
	when the program dies on a signal.
	</p>
	</li>
	</ul></div>
	</div>
	</div>
	<h2 id="_the_functions">The functions</h2>
	<div class="sectionbody">
	<div class="vlist"><dl>
	<dt>
	hold_lock_file_for_update
	</dt>
	<dd>
	<p>
	Take a pointer to <tt>struct lock_file</tt>, the filename of
	the final destination (e.g. <tt>$GIT_DIR/index</tt>) and a flag
	<tt>die_on_error</tt>. Attempt to create a lockfile for the
	destination and return the file descriptor for writing
	to the file. If <tt>die_on_error</tt> flag is true, it dies if
	a lock is already taken for the file; otherwise it
	returns a negative integer to the caller on failure.
	</p>
	</dd>
	<dt>
	commit_lock_file
	</dt>
	<dd>
	<p>
	Take a pointer to the <tt>struct lock_file</tt> initialized
	with an earlier call to <tt>hold_lock_file_for_update()</tt>,
	close the file descriptor and rename the lockfile to its
	final destination. Returns 0 upon success, a negative
	value on failure to close(2) or rename(2).
	</p>
	</dd>
	<dt>
	rollback_lock_file
	</dt>
	<dd>
	<p>
	Take a pointer to the <tt>struct lock_file</tt> initialized
	with an earlier call to <tt>hold_lock_file_for_update()</tt>,
	close the file descriptor and remove the lockfile.
	</p>
	</dd>
	<dt>
	close_lock_file
	</dt>
	<dd>
	<p>
	Take a pointer to the <tt>struct lock_file</tt> initialized
	with an earlier call to <tt>hold_lock_file_for_update()</tt>,
	and close the file descriptor. Returns 0 upon success,
	a negative value on failure to close(2).
	</p>
	</dd>
	</dl></div>
	<div class="para"><p>Because the structure is used in an <tt>atexit(3)</tt> handler, its
	storage has to stay throughout the life of the program. It
	cannot be an auto variable allocated on the stack.</p></div>
	<div class="para"><p>Call <tt>commit_lock_file()</tt> or <tt>rollback_lock_file()</tt> when you are
	done writing to the file descriptor. If you do not call either
	and simply <tt>exit(3)</tt> from the program, an <tt>atexit(3)</tt> handler
	will close and remove the lockfile.</p></div>
	<div class="para"><p>If you need to close the file descriptor you obtained from
	<tt>hold_lock_file_for_update</tt> function yourself, do so by calling
	<tt>close_lock_file()</tt>. You should never call <tt>close(2)</tt> yourself!
	Otherwise the <tt>struct
	lock_file</tt> structure still remembers that the file descriptor
	needs to be closed, and a later call to <tt>commit_lock_file()</tt> or
	<tt>rollback_lock_file()</tt> will result in duplicate calls to
	<tt>close(2)</tt>. Worse yet, if you <tt>close(2)</tt>, open another file
	descriptor for completely different purpose, and then call
	<tt>commit_lock_file()</tt> or <tt>rollback_lock_file()</tt>, they may close
	that unrelated file descriptor.</p></div>
	</div>
	<div id="footer">
	<div id="footer-text">
	Last updated 2009-02-14 08:18:54 UTC
	</div>
	</div>
	</body>
	</html>