Libc-1439.100.3.tar.gz

[apple/libc.git] / gen / FreeBSD / err.3

diff --git a/gen/FreeBSD/err.3 b/gen/FreeBSD/err.3
index 75e5f2b82af2c828a0bcc713095035d3e601eac9..a4c953f0d87062d23c6ed30aa679a6ef903b51c2 100644 (file)
--- a/gen/FreeBSD/err.3
+++ b/gen/FreeBSD/err.3
@@ -9,10 +9,6 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
@@ -30,9 +26,9 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    From: @(#)err.3 8.1 (Berkeley) 6/9/93
-.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.19 2002/08/05 06:49:58 mike Exp $
+.\" $FreeBSD: src/lib/libc/gen/err.3,v 1.24 2008/10/31 15:14:40 rwatson Exp $
 .\"
-.Dd March 6, 1999
+.Dd May 20, 2008
 .Dt ERR 3
 .Os
 .Sh NAME
@@ -49,6 +45,9 @@
 .Nm warnx ,
 .Nm vwarnx ,
 .Nm err_set_exit ,
+#ifdef UNIFDEF_BLOCKS
+.Nm err_set_exit_b ,
+#endif
 .Nm err_set_file
 .Nd formatted error messages
 .Sh LIBRARY
@@ -59,6 +58,10 @@
 .Fn err "int eval" "const char *fmt" "..."
 .Ft void
 .Fn err_set_exit "void (*exitf)(int)"
+#ifdef UNIFDEF_BLOCKS
+.Ft void
+.Fn err_set_exit_b "void (^exitb)(int)"
+#endif
 .Ft void
 .Fn err_set_file "void *vfp"
 .Ft void
@@ -98,7 +101,7 @@ and a space are output.
 If the
 .Fa fmt
 argument is not NULL, the
-.Xr printf 3
+.Xr printf 3 Ns
 -like formatted error message is output.
 The output is terminated by a newline character.
 .Pp
@@ -114,7 +117,7 @@ and
 .Fn vwarnc
 functions append an error message obtained from
 .Xr strerror 3
-based on a code or the global variable
+based on a supplied error code value or the global variable
 .Va errno ,
 preceded by another colon and space unless the
 .Fa fmt
@@ -158,6 +161,10 @@ and
 .Fn verrx
 functions do not return, but exit with the value of the argument
 .Fa eval .
+It is recommended that the standard values defined in
+.Xr sysexits 3
+be used for the value of
+.Fa eval .
 The
 .Fn err_set_exit
 function can be used to specify a function which is called before
@@ -165,6 +172,24 @@ function can be used to specify a function which is called before
 to perform any necessary cleanup; passing a null function pointer for
 .Va exitf
 resets the hook to do nothing.
+#ifdef UNIFDEF_BLOCKS
+The
+.Fn err_set_exit_b
+function is like
+.Fn err_set_exit
+except it takes a block pointer instead of a function pointer.
+.Bd -ragged -offset indent
+Note: The
+.Fn Block_copy
+function (defined in
+.In Blocks.h )
+is used by
+.Fn err_set_exit_b
+to make a copy of the block, especially for the case when a stack-based
+block might go out of scope when the subroutine returns.
+.Ed
+.Pp
+#endif
 The
 .Fn err_set_file
 function sets the output stream used by the other functions.
@@ -178,15 +203,16 @@ or a null pointer
 Display the current errno information string and exit:
 .Bd -literal -offset indent
 if ((p = malloc(size)) == NULL)
-       err(1, NULL);
+       err(EX_OSERR, NULL);
 if ((fd = open(file_name, O_RDONLY, 0)) == -1)
-       err(1, "%s", file_name);
+       err(EX_NOINPUT, "%s", file_name);
 .Ed
 .Pp
 Display an error message and exit:
 .Bd -literal -offset indent
 if (tm.tm_hour < START_TIME)
-       errx(1, "too early, wait until %s", start_time_string);
+       errx(EX_DATAERR, "too early, wait until %s",
+           start_time_string);
 .Ed
 .Pp
 Warn of an error:
@@ -195,7 +221,7 @@ if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
        warnx("%s: %s: trying the block device",
            raw_device, strerror(errno));
 if ((fd = open(block_device, O_RDONLY, 0)) == -1)
-       err(1, "%s", block_device);
+       err(EX_OSFILE, "%s", block_device);
 .Ed
 .Pp
 Warn of an error without using the global variable
@@ -209,7 +235,8 @@ if (error != 0)
 .Xr exit 3 ,
 .Xr fmtmsg 3 ,
 .Xr printf 3 ,
-.Xr strerror 3
+.Xr strerror 3 ,
+.Xr sysexits 3
 .Sh HISTORY
 The
 .Fn err
@@ -229,3 +256,8 @@ and
 .Fn warnc
 functions first appeared in
 .Fx 3.0 .
+#ifdef UNIFDEF_BLOCKS
+The
+.Fn err_set_exit_b
+function first appeared in Mac OS X 10.6.
+#endif