23b61be0d

Rob Landley

2006-08-04

SOURCE BUG Duration: 31s

Subject

Add comments to all the functions in this file documenting what they're for.

SOURCE BUG

This commit was genuinely broken at the time (not related to our build system): scripts/config/mkconfigs.c (2005-08-01 - 2006-10-05 arasi) uretilen bbconfigopts.h icine .config satirlarini kacissiz, ham newline'larla gömüyordu - gecerli C degildi, busybox'un kendi bb_mkdep araci bile parse edemiyordu (7d219aab7 ile duzeltildi, mkconfigs shell scripte cevrildi)

→ Bu hatanin tam hikayesini ve duzeltme diffini gor

Binary

No binary (build failed)

Architecture & Compiler Flags

Architecture: x86_64-linux-gnu Compiler: gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0

—

Build Log

(log yok)

Commit Diff GitHub →

libbb/xfuncs.c +76 -33

libbb/xfuncs.c+76 -33

@@ -11,8 +11,13 @@

	#include "busybox.h"

+	/* All the functions starting with "x" call bb_error_msg_and_die() if they
+	* fail, so callers never need to check for errors. If it returned, it
+	* succeeded. */
+
	#ifndef DMALLOC
	#ifdef L_xmalloc
+	// Die if we can't allocate size bytes of memory.
	void *xmalloc(size_t size)
	{
	void *ptr = malloc(size);
@@ -23,6 +28,9 @@ void *xmalloc(size_t size)
	#endif

	#ifdef L_xrealloc
+	// Die if we can't resize previously allocated memory. (This returns a pointer
+	// to the new memory, which may or may not be the same as the old memory.
+	// It'll copy the contents to a new chunk and free the old one if necessary.)
	void xrealloc(void ptr, size_t size)
	{
	ptr = realloc(ptr, size);
@@ -33,6 +41,7 @@ void xrealloc(void ptr, size_t size)
	#endif

	#ifdef L_xzalloc
+	// Die if we can't allocate and zero size bytes of memory.
	void *xzalloc(size_t size)
	{
	void *ptr = xmalloc(size);
@@ -44,7 +53,8 @@ void *xzalloc(size_t size)
	#endif /* DMALLOC */

	#ifdef L_xstrdup
-	char * xstrdup (const char *s)
+	// Die if we can't copy a string to freshly allocated memory.
+	char * xstrdup(const char *s)
	{
	char *t;

@@ -61,7 +71,9 @@ char * xstrdup (const char *s)
	#endif

	#ifdef L_xstrndup
-	char * xstrndup (const char *s, int n)
+	// Die if we can't allocate n+1 bytes (space for the null terminator) and copy
+	// the (possibly truncated to length n) string into it.
+	char * xstrndup(const char *s, int n)
	{
	char *t;

@@ -75,6 +87,8 @@ char * xstrndup (const char *s, int n)
	#endif

	#ifdef L_xfopen
+	// Die if we can't open a file and return a FILE * to it.
+	// Notice we haven't got xfread(), This is for use with fscanf() and friends.
	FILE xfopen(const char path, const char *mode)
	{
	FILE *fp;
@@ -85,13 +99,18 @@ FILE xfopen(const char path, const char *mode)
	#endif

	#ifdef L_xopen
+	// Die if we can't open an existing file and return an fd.
	int xopen(const char *pathname, int flags)
	{
+	if (ENABLE_DEBUG && (flags && O_CREAT))
+	bb_error_msg_and_die("xopen() with O_CREAT\n");
+
	return xopen3(pathname, flags, 0777);
	}
	#endif

	#ifdef L_xopen3
+	// Die if we can't open a new file and return an fd.
	int xopen3(const char *pathname, int flags, int mode)
	{
	int ret;
@@ -105,9 +124,7 @@ int xopen3(const char *pathname, int flags, int mode)
	#endif

	#ifdef L_xread
-
	// Die with an error message if we can't read the entire buffer.
-
	void xread(int fd, void *buf, size_t count)
	{
	while (count) {
@@ -122,9 +139,7 @@ void xread(int fd, void *buf, size_t count)
	#endif

	#ifdef L_xwrite
-
	// Die with an error message if we can't write the entire buffer.
-
	void xwrite(int fd, void *buf, size_t count)
	{
	while (count) {
@@ -139,9 +154,7 @@ void xwrite(int fd, void *buf, size_t count)
	#endif

	#ifdef L_xlseek
-
-	// Die if we can't lseek to the right spot.
-
+	// Die with an error message if we can't lseek to the right spot.
	void xlseek(int fd, off_t offset, int whence)
	{
	if (offset != lseek(fd, offset, whence)) bb_error_msg_and_die("lseek");
@@ -149,6 +162,7 @@ void xlseek(int fd, off_t offset, int whence)
	#endif

	#ifdef L_xread_char
+	// Die with an error message if we can't read one character.
	unsigned char xread_char(int fd)
	{
	char tmp;
@@ -160,6 +174,7 @@ unsigned char xread_char(int fd)
	#endif

	#ifdef L_xferror
+	// Die with supplied error message if this FILE * has ferror set.
	void xferror(FILE fp, const char fn)
	{
	if (ferror(fp)) {
@@ -169,6 +184,7 @@ void xferror(FILE fp, const char fn)
	#endif

	#ifdef L_xferror_stdout
+	// Die with an error message if stdout has ferror set.
	void xferror_stdout(void)
	{
	xferror(stdout, bb_msg_standard_output);
@@ -176,6 +192,7 @@ void xferror_stdout(void)
	#endif

	#ifdef L_xfflush_stdout
+	// Die with an error message if we have trouble flushing stdout.
	void xfflush_stdout(void)
	{
	if (fflush(stdout)) {
@@ -185,7 +202,8 @@ void xfflush_stdout(void)
	#endif

	#ifdef L_spawn
-	// This does a fork/exec in one call, using vfork().
+	// This does a fork/exec in one call, using vfork(). Return PID of new child,
+	// -1 for failure. Runs argv[0], searching path if that has no / in it.
	pid_t spawn(char **argv)
	{
	static int failed;
@@ -211,6 +229,7 @@ pid_t spawn(char **argv)
	#endif

	#ifdef L_xspawn
+	// Die with an error message if we can't spawn a child process.
	pid_t xspawn(char **argv)
	{
	pid_t pid = spawn(argv);
@@ -220,6 +239,7 @@ pid_t xspawn(char **argv)
	#endif

	#ifdef L_wait4
+	// Wait for the specified child PID to exit, returning child's error return.
	int wait4pid(int pid)
	{
	int status;
@@ -232,11 +252,9 @@ int wait4pid(int pid)
	#endif

	#ifdef L_itoa
-	// Largest 32 bit integer is -2 billion plus null terminator.
-	// Int should always be 32 bits on a Unix-oid system, see
-	// http://www.unix.org/whitepapers/64bit.html
-	static char local_buf[12];
-
+	// Convert unsigned integer to ascii, writing into supplied buffer. A
+	// truncated result is always null terminated (unless buflen is 0), and
+	// contains the first few digits of the result ala strncpy.
	void utoa_to_buf(unsigned n, char *buf, unsigned buflen)
	{
	int i, out = 0;
@@ -254,15 +272,7 @@ void utoa_to_buf(unsigned n, char *buf, unsigned buflen)
	}
	}

-	// Note: uses static buffer, calling it twice in a row will overwrite.
-
-	char *utoa(unsigned n)
-	{
-	utoa_to_buf(n, local_buf, sizeof(local_buf));
-
-	return local_buf;
-	}
-
+	// Convert signed integer to ascii, like utoa_to_buf()
	void itoa_to_buf(int n, char *buf, unsigned buflen)
	{
	if (buflen && n<0) {
@@ -273,8 +283,24 @@ void itoa_to_buf(int n, char *buf, unsigned buflen)
	utoa_to_buf((unsigned)n, buf, buflen);
	}

-	// Note: uses static buffer, calling it twice in a row will overwrite.
+	// The following two functions use a static buffer, so calling either one a
+	// second time will overwrite previous results.
+	//
+	// The largest 32 bit integer is -2 billion plus null terminator, or 12 bytes.
+	// Int should always be 32 bits on any remotely Unix-like system, see
+	// http://www.unix.org/whitepapers/64bit.html for the reasons why.

+	static char local_buf[12];
+
+	// Convert unsigned integer to ascii using a static buffer (returned).
+	char *utoa(unsigned n)
+	{
+	utoa_to_buf(n, local_buf, sizeof(local_buf));
+
+	return local_buf;
+	}
+
+	// Convert signed integer to ascii using a static buffer (returned).
	char *itoa(int n)
	{
	itoa_to_buf(n, local_buf, sizeof(local_buf));
@@ -284,11 +310,15 @@ char *itoa(int n)
	#endif

	#ifdef L_setuid
+	// Die with an error message if we can't set gid. (Because resource limits may
+	// limit this user to a given number of processes, and if that fills up the
+	// setgid() will fail and we'll _still_be_root_, which is bad.)
	void xsetgid(gid_t gid)
	{
	if (setgid(gid)) bb_error_msg_and_die("setgid");
	}

+	// Die with an error message if we cant' set uid. (See xsetgid() for why.)
	void xsetuid(uid_t uid)
	{
	if (setuid(uid)) bb_error_msg_and_die("setuid");
@@ -296,6 +326,7 @@ void xsetuid(uid_t uid)
	#endif

	#ifdef L_fdlength
+	// Return how long the file at fd is, if there's any way to determine it.
	off_t fdlength(int fd)
	{
	off_t bottom = 0, top = 0, pos;
@@ -305,7 +336,8 @@ off_t fdlength(int fd)

	if (ioctl(fd, BLKGETSIZE, &size) >= 0) return size*512;

-	// If not, do a binary search for the last location we can read.
+	// If not, do a binary search for the last location we can read. (Some
+	// block devices don't do BLKGETSIZE right.)

	do {
	char temp;
@@ -334,6 +366,8 @@ off_t fdlength(int fd)
	#endif

	#ifdef L_xasprintf
+	// Die with an error message if we can't malloc() enough space and do an
+	// sprintf() into that space.
	char xasprintf(const char format, ...)
	{
	va_list p;
@@ -362,6 +396,8 @@ char xasprintf(const char format, ...)
	#endif

	#ifdef L_xprint_and_close_file
+	// Die with an error message if we can't copy an entire FILE * to stdout, then
+	// close that file.
	void xprint_and_close_file(FILE *file)
	{
	// copyfd outputs error messages for us.
@@ -372,6 +408,7 @@ void xprint_and_close_file(FILE *file)
	#endif

	#ifdef L_xchdir
+	// Die if we can't chdir to a new path.
	void xchdir(const char *path)
	{
	if (chdir(path))
@@ -380,6 +417,7 @@ void xchdir(const char *path)
	#endif

	#ifdef L_warn_opendir
+	// Print a warning message if opendir() fails, but don't die.
	DIR warn_opendir(const char path)
	{
	DIR *dp;
@@ -393,6 +431,7 @@ DIR warn_opendir(const char path)
	#endif

	#ifdef L_xopendir
+	// Die with an error message if opendir() fails.
	DIR xopendir(const char path)
	{
	DIR *dp;
@@ -405,6 +444,7 @@ DIR xopendir(const char path)

	#ifdef L_xdaemon
	#ifndef BB_NOMMU
+	// Die with an error message if we can't daemonize.
	void xdaemon(int nochdir, int noclose)
	{
	if (daemon(nochdir, noclose)) bb_perror_msg_and_die("daemon");
@@ -412,14 +452,8 @@ void xdaemon(int nochdir, int noclose)
	#endif
	#endif

-	#ifdef L_xbind
-	void xbind(int sockfd, struct sockaddr *my_addr, socklen_t addrlen)
-	{
-	if (bind(sockfd, my_addr, addrlen)) bb_perror_msg_and_die("bind");
-	}
-	#endif
-
	#ifdef L_xsocket
+	// Die with an error message if we can't open a new socket.
	int xsocket(int domain, int type, int protocol)
	{
	int r = socket(domain, type, protocol);
@@ -430,7 +464,16 @@ int xsocket(int domain, int type, int protocol)
	}
	#endif

+	#ifdef L_xbind
+	// Die with an error message if we can't bind a socket to an address.
+	void xbind(int sockfd, struct sockaddr *my_addr, socklen_t addrlen)
+	{
+	if (bind(sockfd, my_addr, addrlen)) bb_perror_msg_and_die("bind");
+	}
+	#endif
+
	#ifdef L_xlisten
+	// Die with an error message if we can't listen for connections on a socket.
	void xlisten(int s, int backlog)
	{
	if (listen(s, backlog)) bb_perror_msg_and_die("listen");