tcl/doc/SetErrno.3

   1 '\"
   2 '\" Copyright (c) 1996 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 '\" RCS: @(#) $Id$
   8 .so man.macros
   9 .TH Tcl_SetErrno 3 8.3 Tcl "Tcl Library Procedures"
  10 .BS
  11 .SH NAME
  12 Tcl_SetErrno, Tcl_GetErrno, Tcl_ErrnoId, Tcl_ErrnoMsg \- manipulate errno to store and retrieve error codes
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 void
  18 \fBTcl_SetErrno\fR(\fIerrorCode\fR)
  19 .sp
  20 int
  21 \fBTcl_GetErrno\fR()
  22 .sp
  23 CONST char *
  24 \fBTcl_ErrnoId\fR()
  25 .sp
  26 CONST char *
  27 \fBTcl_ErrnoMsg\fR(\fIerrorCode\fR)
  28 .sp
  29 .SH ARGUMENTS
  30 .AS int errorCode in
  31 .AP int errorCode in
  32 A POSIX error code such as \fBENOENT\fR.
  33 .BE
  34
  35 .SH DESCRIPTION
  36 .PP
  37 \fBTcl_SetErrno\fR and \fBTcl_GetErrno\fR provide portable access
  38 to the \fBerrno\fR variable, which is used to record a POSIX error
  39 code after system calls and other operations such as \fBTcl_Gets\fR.
  40 These procedures are necessary because global variable accesses cannot
  41 be made across module boundaries on some platforms.
  42 .PP
  43 \fBTcl_SetErrno\fR sets the \fBerrno\fR variable to the value of the
  44 \fIerrorCode\fR argument
  45 C procedures that wish to return error information to their callers
  46 via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting
  47 \fBerrno\fR directly.
  48 .PP
  49 \fBTcl_GetErrno\fR returns the current value of \fBerrno\fR.
  50 Procedures wishing to access \fBerrno\fR should call this procedure
  51 instead of accessing \fBerrno\fR directly.
  52 .PP
  53 \fBTcl_ErrnoId\fR and \fBTcl_ErrnoMsg\fR return string
  54 representations of \fBerrno\fR values.  \fBTcl_ErrnoId\fR
  55 returns a machine-readable textual identifier such as
  56 "EACCES" that corresponds to the current value of \fBerrno\fR.
  57 \fBTcl_ErrnoMsg\fR returns a human-readable string such as
  58 "permission denied" that corresponds to the value of its
  59 \fIerrorCode\fR argument.  The \fIerrorCode\fR argument is
  60 typically the value returned by \fBTcl_GetErrno\fR.
  61 The strings returned by these functions are
  62 statically allocated and the caller must not free or modify them.
  63
  64 .SH KEYWORDS
  65 errno, error code, global variables