1explain_rename(3)          Library Functions Manual          explain_rename(3)
2
3
4

NAME

6       explain_rename - explain rename(2) errors
7

SYNOPSIS

9       #include <libexplain/rename.h>
10       const char *explain_rename(const char *oldpath, const char *newpath);
11       const char *explain_errno_rename(int errnum, const char *oldpath, const
12       char *newpath);
13       void explain_message_rename(char *message, int message_size, const char
14       *oldpath, const char *newpath);
15       void  explain_message_errno_rename(char *message, int message_size, int
16       errnum, const char *oldpath, const char *newpath);
17

DESCRIPTION

19       The functions declared in the <libexplain/rename.h> include file may be
20       used to explain errors returned by the rename(2) system call.
21
22   explain_rename
23       const char *explain_rename(const char *oldpath, const char *newpath);
24
25       The  explain_rename  function  is  used  to obtain an explanation of an
26       error returned by the rename(2) function.  The least the  message  will
27       contain  is  the  value of strerror(errno), but usually it will do much
28       better, and indicate the underlying cause in more detail.
29
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       This  function  is intended to be used in a fashion similar to the fol‐
34       lowing example:
35              if (rename(oldpath, rewpath) < 0)
36              {
37                  fprintf(stderr, "%s\n", explain_rename(oldpath, newpath));
38                  exit(EXIT_FAILURE);
39              }
40
41       oldpath The original oldpath, exactly as passed to the rename(2) system
42               call.
43
44       newpath The original newpath, exactly as passed to the rename(2) system
45               call.
46
47       Returns:
48               The message explaining  the  error.   This  message  buffer  is
49               shared by all libexplain functions which do not supply a buffer
50               in their argument list.  This will be overwritten by  the  next
51               call  to  any  libexplain  function  which  shares this buffer,
52               including other threads.
53
54       Note: This function is not thread safe, because it shares a return buf‐
55       fer across all threads, and many other functions in this library.
56
57   explain_errno_rename
58       const char *explain_errno_rename(int errnum, const char *oldpath, const
59       char *newpath);
60
61       The explain_errno_rename function is used to obtain an  explanation  of
62       an  error  returned  by  the rename(2) function.  The least the message
63       will contain is the value of strerror(errnum), but usually it  will  do
64       much better, and indicate the underlying cause in more detail.
65
66       This  function  is intended to be used in a fashion similar to the fol‐
67       lowing example:
68              if (rename(oldpath, newpath) < 0)
69              {
70                  int err = errno;
71                  fprintf(stderr, "%s\n", explain_errno_rename(err, oldpath,
72                      newpath));
73                  exit(EXIT_FAILURE);
74              }
75
76       errnum  The error value to be decoded, usually obtained from the  errno
77               global  variable  just before this function is called.  This is
78               necessary if you need to call any code between the system  call
79               to  be explained and this function, because many libc functions
80               will alter the value of errno.
81
82       oldpath The original oldpath, exactly as passed to the rename(2) system
83               call.
84
85       newpath The original newpath, exactly as passed to the rename(2) system
86               call.
87
88       Returns:
89               The message explaining  the  error.   This  message  buffer  is
90               shared by all libexplain functions which do not supply a buffer
91               in their argument list.  This will be overwritten by  the  next
92               call  to  any  libexplain  function  which  shares this buffer,
93               including other threads.
94
95       Note: This function is not thread safe, because it shares a return buf‐
96       fer across all threads, and many other functions in this library.
97
98   explain_message_rename
99       void explain_message_rename(char *message, int message_size, const char
100       *oldpath, const char *newpath);
101
102       The explain_message_rename function is used to obtain an explanation of
103       an  error  returned  by  the rename(2) function.  The least the message
104       will contain is the value of strerror(errno), but usually  it  will  do
105       much better, and indicate the underlying cause in more detail.
106
107       The  errno global variable will be used to obtain the error value to be
108       decoded.
109
110       This function is intended to be used in a fashion similar to  the  fol‐
111       lowing example:
112              if (rename(oldpath, newpath) < 0)
113              {
114                  char message[3000];
115                  explain_message_rename(message, sizeof(message), oldpath,
116                      newpath);
117                  fprintf(stderr, "%s\n", message);
118                  exit(EXIT_FAILURE);
119              }
120
121       message The location in which to store the returned message.  Because a
122               message return buffer  has  been  supplied,  this  function  is
123               thread safe, if the buffer is thread safe.
124
125       message_size
126               The  size  in  bytes  of  the  location  in  which to store the
127               returned message.
128
129       oldpath The original oldpath, exactly as passed to the rename(2) system
130               call.
131
132       newpath The original newpath, exactly as passed to the rename(2) system
133               call.
134
135   explain_message_errno_rename
136       void explain_message_errno_rename(char *message, int message_size,  int
137       errnum, const char *oldpath, const char *newpath);
138
139       The explain_message_errno_rename function is used to obtain an explana‐
140       tion of an error returned by the rename(2)  function.   The  least  the
141       message  will  contain is the value of strerror(errnum), but usually it
142       will do much better, and indicate the underlying cause in more detail.
143
144       This function is intended to be used in a fashion similar to  the  fol‐
145       lowing example:
146              if (rename(oldpath, newpath) < 0)
147              {
148                  int err = errno;
149                  char message[3000];
150                  explain_message_errno_rename(message, sizeof(message), err,
151                      oldpath, newpath);
152                  fprintf(stderr, "%s\n", message);
153                  exit(EXIT_FAILURE);
154              }
155
156       message The location in which to store the returned message.  Because a
157               message return buffer  has  been  supplied,  this  function  is
158               thread safe, given a thread safe buffer.
159
160       message_size
161               The  size  in  bytes  of  the  location  in  which to store the
162               returned message.
163
164       errnum  The error value to be decoded, usually obtained from the  errno
165               global  variable  just before this function is called.  This is
166               necessary if you need to call any code between the system  call
167               to  be explained and this function, because many libc functions
168               will alter the value of errno.
169
170       oldpath The original oldpath, exactly as passed to the rename(2) system
171               call.
172
173       newpath The original newpath, exactly as passed to the rename(2) system
174               call.
175
177       libexplain version 0.40
178       Copyright (C) 2008 Peter Miller
179

AUTHOR

181       Written by Peter Miller <pmiller@opensource.org.au>
182
183
184
185                                                             explain_rename(3)
Impressum