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

NAME

6       explain_link - explain link(2) errors
7

SYNOPSIS

9       #include <libexplain/link.h>
10       const char *explain_link(const char *oldpath, const char *newpath);
11       const  char  *explain_errno_link(int errnum, const char *oldpath, const
12       char *newpath);
13       void explain_message_link(char *message, int message_size,  const  char
14       *oldpath, const char *newpath);
15       void  explain_message_errno_link(char  *message,  int message_size, int
16       errnum, const char *oldpath, const char *newpath);
17

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the link(2) system call.
21
22   explain_link
23       const char *explain_link(const char *oldpath, const char *newpath);
24
25       The  explain_link function is used to obtain an explanation of an error
26       returned by the link(2) system call.  The least the message  will  con‐
27       tain  is the value of strerror(errno), but usually it will do much bet‐
28       ter, 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 (link(oldpath, newpath) < 0)
36              {
37                  fprintf(stderr, "%s\n", explain_link(oldpath, newpath));
38                  exit(EXIT_FAILURE);
39              }
40
41       oldpath The original oldpath, exactly as passed to the  link(2)  system
42               call.
43
44       newpath The  original  newpath, exactly as passed to the link(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_link
58       const  char  *explain_errno_link(int errnum, const char *oldpath, const
59       char *newpath);
60
61       The explain_errno_link function is used to obtain an explanation of  an
62       error  returned by the link(2) system call.  The least the message will
63       contain is the value of strerror(errnum), but usually it will  do  much
64       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 (link(oldpath, newpath) < 0)
69              {
70                  int err = errno;
71                  fprintf(stderr, "%s\n", explain_errno_link(err, oldpath, newpath));
72                  exit(EXIT_FAILURE);
73              }
74
75       errnum  The error value to be decoded, usually obtained from the  errno
76               global  variable  just before this function is called.  This is
77               necessary if you need to call any code between the system  call
78               to  be explained and this function, because many libc functions
79               will alter the value of errno.
80
81       oldpath The original oldpath, exactly as passed to the  link(2)  system
82               call.
83
84       newpath The  original  newpath, exactly as passed to the link(2) system
85               call.
86
87       Returns:
88               The message explaining  the  error.   This  message  buffer  is
89               shared by all libexplain functions which do not supply a buffer
90               in their argument list.  This will be overwritten by  the  next
91               call  to  any  libexplain  function  which  shares this buffer,
92               including other threads.
93
94       Note: This function is not thread safe, because it shares a return buf‐
95       fer across all threads, and many other functions in this library.
96
97   explain_message_link
98       void  explain_message_link(char  *message, int message_size, const char
99       *oldpath, const char *newpath);
100
101       The explain_message_link function may be used to  obtain an explanation
102       of an error returned by the link(2) system call.  The least the message
103       will contain is the value of strerror(errno), but usually  it  will  do
104       much better, and indicate the underlying cause in more detail.
105
106       The  errno global variable will be used to obtain the error value to be
107       decoded.
108
109       This function is intended to be used in a fashion similar to  the  fol‐
110       lowing example:
111              if (link(oldpath, newpath) < 0)
112              {
113                  char message[3000];
114                  explain_message_link(message, sizeof(message), oldpath, newpath);
115                  fprintf(stderr, "%s\n", message);
116                  exit(EXIT_FAILURE);
117              }
118
119       message The  location  in  which  to  store the returned message.  If a
120               suitable message return buffer is supplied,  this  function  is
121               thread safe.
122
123       message_size
124               The  size  in  bytes  of  the  location  in  which to store the
125               returned message.
126
127       oldpath The original oldpath, exactly as passed to the  link(2)  system
128               call.
129
130       newpath The  original  newpath, exactly as passed to the link(2) system
131               call.
132
133   explain_message_errno_link
134       void explain_message_errno_link(char *message,  int  message_size,  int
135       errnum, const char *oldpath, const char *newpath);
136
137       The explain_message_errno_link function may be used to obtain an expla‐
138       nation of an error returned by the link(2) system call.  The least  the
139       message  will  contain is the value of strerror(errnum), but usually it
140       will do much better, and indicate the underlying cause in more detail.
141
142       This function is intended to be used in a fashion similar to  the  fol‐
143       lowing example:
144              if (link(oldpath, newpath) < 0)
145              {
146                  int err = errno;
147                  char message[3000];
148                  explain_message_errno_link(message, sizeof(message), err,
149                      oldpath, newpath);
150                  fprintf(stderr, "%s\n", message);
151                  exit(EXIT_FAILURE);
152              }
153
154       message The  location  in  which  to  store the returned message.  If a
155               suitable message return buffer is supplied,  this  function  is
156               thread safe.
157
158       message_size
159               The  size  in  bytes  of  the  location  in  which to store the
160               returned message.
161
162       errnum  The error value to be decoded, usually obtained from the  errno
163               global  variable  just before this function is called.  This is
164               necessary if you need to call any code between the system  call
165               to  be explained and this function, because many libc functions
166               will alter the value of errno.
167
168       oldpath The original oldpath, exactly as passed to the  link(2)  system
169               call.
170
171       newpath The  original  newpath, exactly as passed to the link(2) system
172               call.
173

SEE ALSO

175       link(2) make a new name for a file
176
177       explain_link_or_die(3)
178               make a new name for a file and report errors
179
181       libexplain version 0.40
182       Copyright (C) 2008 Peter Miller
183
184
185
186                                                               explain_link(3)
Impressum