Document functions xmemdupz(), xread() and xwrite()

heikkiorsila · gitster · commit e8729f538078 · 2008-04-27T22:22:14.000-07:00
Signed-off-by: Heikki Orsila &lt;heikki.orsila@iki.fi&gt;
Signed-off-by: Junio C Hamano &lt;gitster@pobox.com&gt;
diff --git a/git-compat-util.h b/git-compat-util.h
@@ -268,6 +268,12 @@ static inline void *xmalloc(size_t size)
 	return ret;
 }
 
+/*
+ * xmemdupz() allocates (len + 1) bytes of memory, duplicates "len" bytes of
+ * "data" to the allocated memory, zero terminates the allocated memory,
+ * and returns a pointer to the allocated memory. If the allocation fails,
+ * the program dies.
+ */
 static inline void *xmemdupz(const void *data, size_t len)
 {
 	char *p = xmalloc(len + 1);
@@ -329,6 +335,11 @@ static inline void *xmmap(void *start, size_t length,
 	return ret;
 }
 
+/*
+ * xread() is the same a read(), but it automatically restarts read()
+ * operations with a recoverable error (EAGAIN and EINTR). xread()
+ * DOES NOT GUARANTEE that "len" bytes is read even if the data is available.
+ */
 static inline ssize_t xread(int fd, void *buf, size_t len)
 {
 	ssize_t nr;
@@ -340,6 +351,11 @@ static inline ssize_t xread(int fd, void *buf, size_t len)
 	}
 }
 
+/*
+ * xwrite() is the same a write(), but it automatically restarts write()
+ * operations with a recoverable error (EAGAIN and EINTR). xwrite() DOES NOT
+ * GUARANTEE that "len" bytes is written even if the operation is successful.
+ */
 static inline ssize_t xwrite(int fd, const void *buf, size_t len)
 {
 	ssize_t nr;

Original file line number	Diff line number	Diff line change
`@@ -268,6 +268,12 @@ static inline void *xmalloc(size_t size)`
`268`	`268`	`return ret;`
`269`	`269`	`}`
`270`	`270`
	`271`	`+/*`
	`272`	`+ * xmemdupz() allocates (len + 1) bytes of memory, duplicates "len" bytes of`
	`273`	`+ * "data" to the allocated memory, zero terminates the allocated memory,`
	`274`	`+ * and returns a pointer to the allocated memory. If the allocation fails,`
	`275`	`+ * the program dies.`
	`276`	`+ */`
`271`	`277`	`static inline void xmemdupz(const void data, size_t len)`
`272`	`278`	`{`
`273`	`279`	`char *p = xmalloc(len + 1);`
`@@ -329,6 +335,11 @@ static inline void xmmap(void start, size_t length,`
`329`	`335`	`return ret;`
`330`	`336`	`}`
`331`	`337`
	`338`	`+/*`
	`339`	`+ * xread() is the same a read(), but it automatically restarts read()`
	`340`	`+ * operations with a recoverable error (EAGAIN and EINTR). xread()`
	`341`	`+ * DOES NOT GUARANTEE that "len" bytes is read even if the data is available.`
	`342`	`+ */`
`332`	`343`	`static inline ssize_t xread(int fd, void *buf, size_t len)`
`333`	`344`	`{`
`334`	`345`	`ssize_t nr;`
`@@ -340,6 +351,11 @@ static inline ssize_t xread(int fd, void *buf, size_t len)`
`340`	`351`	`}`
`341`	`352`	`}`
`342`	`353`
	`354`	`+/*`
	`355`	`+ * xwrite() is the same a write(), but it automatically restarts write()`
	`356`	`+ * operations with a recoverable error (EAGAIN and EINTR). xwrite() DOES NOT`
	`357`	`+ * GUARANTEE that "len" bytes is written even if the operation is successful.`
	`358`	`+ */`
`343`	`359`	`static inline ssize_t xwrite(int fd, const void *buf, size_t len)`
`344`	`360`	`{`
`345`	`361`	`ssize_t nr;`