casacore
SymLink.h
Go to the documentation of this file.
1 //# SymLink.h: Get information about, and manipulate symbolic links
2 //# Copyright (C) 1996
3 //# Associated Universities, Inc. Washington DC, USA.
4 //#
5 //# This library is free software; you can redistribute it and/or modify it
6 //# under the terms of the GNU Library General Public License as published by
7 //# the Free Software Foundation; either version 2 of the License, or (at your
8 //# option) any later version.
9 //#
10 //# This library is distributed in the hope that it will be useful, but WITHOUT
11 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 //# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 //# License for more details.
14 //#
15 //# You should have received a copy of the GNU Library General Public License
16 //# along with this library; if not, write to the Free Software Foundation,
17 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18 //#
19 //# Correspondence concerning AIPS++ should be addressed as follows:
20 //# Internet email: aips2-request@nrao.edu.
21 //# Postal address: AIPS++ Project Office
22 //# National Radio Astronomy Observatory
23 //# 520 Edgemont Road
24 //# Charlottesville, VA 22903-2475 USA
25 //#
26 //# $Id$
27 
28 
29 #ifndef CASA_SYMLINK_H
30 #define CASA_SYMLINK_H
31 
32 //# Includes
33 #include <casacore/casa/aips.h>
34 #include <casacore/casa/OS/Path.h>
35 #include <casacore/casa/OS/File.h>
36 
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 // <summary>
41 // Get information about, and manipulate symbolic links
42 // </summary>
43 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
44 // </reviewed>
45 
46 // <use visibility=export>
47 
48 // <prerequisite>
49 // <li> Basic knowledge of the UNIX file system
50 // <li> <linkto class=File>File</linkto>
51 // </prerequisite>
52 
53 // <etymology>
54 // The class SymLink handles SYMbolic LINKs in the file system.
55 // </etymology>
56 
57 // <synopsis>
58 // SymLink provides functions to manipulate and to get information about
59 // symbolic links. The functions for getting information (like ownership,
60 // dates) about symbolic links are inherited from the
61 // <linkto class=File>File</linkto> class.
62 // <br>
63 // The class SymLink itself provides functions to create, remove, copy, and
64 // move symbolic links. There is a function readSymLink which reads a link and
65 // then returns a path and there is a function followSymLink which reads a
66 // link recursively. If the link eventually refers to itself (a loop),
67 // an exception will be thrown.
68 // </synopsis>
69 
70 // <example>
71 // <srcblock>
72 // SymLink symLink1("isLink");
73 // SymLink symLink2("isLink2");
74 // SymLink symLinkA("A");
75 // SymLink symLinkB("B");
76 //
77 // symLink1.create("~", True); // Create a symbolic link to the home
78 // // directory. When it exists it will be
79 // // overwritten.
80 // symLink2.create("isLink", False); // Create a symbolic link to
81 // // isLink. When it exists it will not
82 // // be overwritten.
83 // symLinkA.create(Path("B")); // Create a recursive link
84 // symLinkB.create(Path("A")); // Create a recursive link
85 //
86 // cout << symLink1.readSymLink() << endl; // The homedirectory is printed
87 // cout << symLink2.readSymLink() << endl; // isLink is printed
88 // cout << symLink2.followSymLink() << endl;// The homedirectory is printed
89 // cout << symLinkA.readSymLink() << endl; // B is printed
90 // cout << symLinkA.followSymLink() << endl;// An exception is thrown (loop)
91 // </srcblock>
92 // </example>
93 
94 // <motivation>
95 // Provide functions for manipulating and getting information
96 // about symbolic links.
97 // </motivation>
98 
99 
100 class SymLink: public File
101 {
102 public:
103 
104  // The default constructor creates a SymLink with path ".".
106 
107  // Create a SymLink with the given path.
108  // An exception is thrown if the path exist and is no symbolic link
109  // or if it does not exist, but cannot be created.
110  // <group>
111  SymLink (const Path& name);
112  SymLink (const String& name);
113  SymLink (const File& name);
114  // </group>
115 
116  // Copy constructor (copy semantics).
117  SymLink (const SymLink& that);
118 
120 
121  // Assignment (copy semantics).
122  SymLink& operator= (const SymLink& that);
123 
124  // Make a symbolic link to a file given by target.
125  // An exception will be thrown if:
126  // <br>-target already exists and is no symlink
127  // <br>-or target already exists and overwrite==False
128  // <group>
129  void create (const Path& target, Bool overwrite = True);
130  void create (const String& target, Bool overwrite = True);
131  // </group>
132 
133  // Copy the symlink to the target path using the system command cp.
134  // The target path can be a directory or a file (as in cp).
135  // An exception is thrown if:
136  // <br>- the target directory is not writable
137  // <br>- or the target file already exists and overwrite==False
138  // <br>- or the target file already exists and is not writable
139  // <group>
140  void copy (const Path& target, Bool overwrite = True) const;
141  void copy (const String& target, Bool overwrite = True) const;
142  // </group>
143 
144  // Move the symlink to the target path using the system command mv.
145  // The target path can be a directory or a file (as in mv).
146  // An exception is thrown if:
147  // <br>- the target directory is not writable
148  // <br>- or the target file already exists and overwrite==False
149  // <br>- or the target file already exists and is not writable
150  // <group>
151  void move (const Path& target, Bool overwrite = True);
152  void move (const String& target, Bool overwrite = True);
153  // </group>
154 
155  // Remove a symbolic link.
156  void remove();
157 
158  // Read value of a symbolic link and return it as a Path. If
159  // the symlink does not exist, an exception will be thrown.
160  // When the symlink points to a file with a relative name,
161  // the resulting file name gets prepended by the dirname of the symlink,
162  // which is similar to the way a shell handles symlinks.
163  // E.g.
164  // <srcblock>
165  // ls > subdir/a
166  // ln -s a subdir/b
167  // more subdir/b
168  // </srcblock>
169  // The more command shows the results of subdir/a.
170  Path readSymLink() const;
171 
172  // As readSymLink, but the entire symlink chain is followed
173  // when the symlinks points to other symlinks.
174  // An exception is thrown if this results in a loop (that is, if more
175  // than 25 links are encountered).
177 
178 private:
179  // Check if the path of the file is valid.
180  // Also resolve possible symlinks.
181  void checkPath() const;
182 
183  // Get the value of the symlink.
185 };
186 
187 
188 inline void SymLink::create (const String& target, Bool overwrite)
189 {
190  create (Path(target), overwrite);
191 }
192 inline void SymLink::copy (const String& target, Bool overwrite) const
193 {
194  copy (Path(target), overwrite);
195 }
196 inline void SymLink::move (const String& target, Bool overwrite)
197 {
198  move (Path(target), overwrite);
199 }
200 
201 
202 
203 } //# NAMESPACE CASACORE - END
204 
205 #endif
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
const Bool True
Definition: aipstype.h:43