Apache Mesos
os.hpp
Go to the documentation of this file.
1 // Licensed under the Apache License, Version 2.0 (the "License");
2 // you may not use this file except in compliance with the License.
3 // You may obtain a copy of the License at
4 //
5 // http://www.apache.org/licenses/LICENSE-2.0
6 //
7 // Unless required by applicable law or agreed to in writing, software
8 // distributed under the License is distributed on an "AS IS" BASIS,
9 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
10 // See the License for the specific language governing permissions and
11 // limitations under the License.
12 
13 #ifndef __STOUT_POSIX_OS_HPP__
14 #define __STOUT_POSIX_OS_HPP__
15 
16 #include <errno.h>
17 #ifdef __sun
18 #include <sys/loadavg.h>
19 #define dirfd(dir) ((dir)->d_fd)
20 #ifndef NAME_MAX
21 #define NAME_MAX MAXNAMLEN
22 #endif // NAME_MAX
23 #else
24 #include <fts.h>
25 #endif // __sun
26 #include <glob.h>
27 #include <grp.h>
28 #include <limits.h>
29 #include <netdb.h>
30 #include <pwd.h>
31 #include <signal.h>
32 #include <stddef.h>
33 #include <stdio.h>
34 #include <stdlib.h>
35 #include <unistd.h>
36 #include <utime.h>
37 
38 #include <sys/ioctl.h>
39 
40 #ifdef __linux__
41 #include <linux/version.h>
42 #include <sys/sysinfo.h>
43 #endif // __linux__
44 
45 #include <sys/ioctl.h>
46 #include <sys/utsname.h>
47 #include <sys/wait.h>
48 
49 #include <list>
50 #include <map>
51 #include <mutex>
52 #include <set>
53 #include <string>
54 #include <vector>
55 
56 #include <stout/synchronized.hpp>
57 
58 #include <stout/os/close.hpp>
59 #include <stout/os/environment.hpp>
60 #include <stout/os/fcntl.hpp>
61 #include <stout/os/find.hpp>
62 #include <stout/os/fork.hpp>
63 #include <stout/os/getcwd.hpp>
64 #include <stout/os/killtree.hpp>
65 #include <stout/os/os.hpp>
66 #include <stout/os/permissions.hpp>
67 #include <stout/os/read.hpp>
68 #include <stout/os/rename.hpp>
69 #include <stout/os/sendfile.hpp>
70 #include <stout/os/signals.hpp>
71 #include <stout/os/strerror.hpp>
72 #include <stout/os/write.hpp>
73 
74 #ifdef __FreeBSD__
75 #include <stout/os/freebsd.hpp>
76 #endif
77 #ifdef __linux__
78 #include <stout/os/linux.hpp>
79 #endif // __linux__
80 #include <stout/os/open.hpp>
81 #ifdef __APPLE__
82 #include <stout/os/osx.hpp>
83 #endif // __APPLE__
84 #ifdef __sun
85 #include <stout/os/sunos.hpp>
86 #endif // __sun
87 
88 #include <stout/os/posix/chown.hpp>
90 
91 #include <stout/os/shell.hpp>
92 
93 namespace os {
94 
95 // Import `::gmtime_r` into `os::` namespace.
97 
98 // Import `::hstrerror` into `os::` namespace.
100 
101 // Import `::random` into `os::` namespace.
103 
104 // Forward declarations.
105 inline Try<Nothing> utime(const std::string&);
107 
108 
109 // Suspends execution of the calling process until a child specified by `pid`
110 // has changed state. Unlike the POSIX standard function `::waitpid`, this
111 // function does not use -1 and 0 to signify errors and nonblocking return.
112 // Instead, we return `Result<pid_t>`:
113 // * In case of error, we return `Error` rather than -1. For example, we
114 // would return an `Error` in case of `EINVAL`.
115 // * In case of nonblocking return, we return `None` rather than 0. For
116 // example, if we pass `WNOHANG` in the `options`, we would expect 0 to be
117 // returned in the case that children specified by `pid` exist, but have
118 // not changed state yet. In this case we return `None` instead.
119 //
120 // NOTE: There are important differences between the POSIX and Windows
121 // implementations of this function:
122 // * On POSIX, `pid_t` is a signed number, but on Windows, PIDs are `DWORD`,
123 // which is `unsigned long`. Thus, if we use `DWORD` to represent the `pid`
124 // argument, we would not be able to pass -1 as the `pid`.
125 // * Since it is important to be able to detect -1 has been passed to
126 // `os::waitpid`, as a matter of practicality, we choose to:
127 // (1) Use `long` to represent the `pid` argument.
128 // (2) Disable using any value <= 0 for `pid` on Windows.
129 // * This decision is pragmatic. The reasoning is:
130 // (1) The Windows code paths call `os::waitpid` in only a handful of
131 // places, and in none of these conditions do we need `-1` as a value.
132 // (2) Since PIDs virtually never take on values outside the range of
133 // vanilla signed `long` it is likely that an accidental conversion
134 // will never happen.
135 // (3) Even though it is not formalized in the C specification, the
136 // implementation of `long` on the vast majority of production servers
137 // is 2's complement, so we expect that when we accidentally do
138 // implicitly convert from `unsigned long` to `long`, we will "wrap
139 // around" to negative values. And since we've disabled the negative
140 // `pid` in the Windows implementation, we should error out.
141 inline Result<pid_t> waitpid(pid_t pid, int* status, int options)
142 {
143  const pid_t child_pid = ::waitpid(pid, status, options);
144 
145  if (child_pid == 0) {
146  return None();
147  } else if (child_pid < 0) {
148  return ErrnoError("os::waitpid: Call to `waitpid` failed");
149  } else {
150  return child_pid;
151  }
152 }
153 
154 
155 // Sets the value associated with the specified key in the set of
156 // environment variables.
157 inline void setenv(const std::string& key,
158  const std::string& value,
159  bool overwrite = true)
160 {
161  ::setenv(key.c_str(), value.c_str(), overwrite ? 1 : 0);
162 }
163 
164 
165 // Unsets the value associated with the specified key in the set of
166 // environment variables.
167 inline void unsetenv(const std::string& key)
168 {
169  ::unsetenv(key.c_str());
170 }
171 
172 
173 // This function is a portable version of execvpe ('p' means searching
174 // executable from PATH and 'e' means setting environments). We add
175 // this function because it is not available on all systems.
176 //
177 // NOTE: This function is not thread safe. It is supposed to be used
178 // only after fork (when there is only one thread). This function is
179 // async signal safe.
180 inline int execvpe(const char* file, char** argv, char** envp)
181 {
182  char** saved = os::raw::environment();
183 
184  *os::raw::environmentp() = envp;
185 
186  int result = execvp(file, argv);
187 
188  *os::raw::environmentp() = saved;
189 
190  return result;
191 }
192 
193 
194 inline Try<Nothing> chmod(const std::string& path, int mode)
195 {
196  if (::chmod(path.c_str(), mode) < 0) {
197  return ErrnoError();
198  }
199 
200  return Nothing();
201 }
202 
203 
205  const std::string& path,
206  mode_t mode,
207  dev_t dev)
208 {
209  if (::mknod(path.c_str(), mode, dev) < 0) {
210  return ErrnoError();
211  }
212 
213  return Nothing();
214 }
215 
216 
217 // Suspends execution for the given duration.
218 inline Try<Nothing> sleep(const Duration& duration)
219 {
220  timespec remaining;
221  remaining.tv_sec = static_cast<long>(duration.secs());
222  remaining.tv_nsec =
223  static_cast<long>((duration - Seconds(remaining.tv_sec)).ns());
224 
225  while (nanosleep(&remaining, &remaining) == -1) {
226  if (errno == EINTR) {
227  continue;
228  } else {
229  return ErrnoError();
230  }
231  }
232 
233  return Nothing();
234 }
235 
236 
237 // Returns the list of files that match the given (shell) pattern.
238 inline Try<std::list<std::string>> glob(const std::string& pattern)
239 {
240  glob_t g;
241  int status = ::glob(pattern.c_str(), GLOB_NOSORT, nullptr, &g);
242 
243  std::list<std::string> result;
244 
245  if (status != 0) {
246  if (status == GLOB_NOMATCH) {
247  return result; // Empty list.
248  } else {
249  return ErrnoError();
250  }
251  }
252 
253  for (size_t i = 0; i < g.gl_pathc; ++i) {
254  result.push_back(g.gl_pathv[i]);
255  }
256 
257  globfree(&g); // Best-effort free of dynamically allocated memory.
258 
259  return result;
260 }
261 
262 
263 // Returns the total number of cpus (cores).
264 inline Try<long> cpus()
265 {
266  long cpus = sysconf(_SC_NPROCESSORS_ONLN);
267 
268  if (cpus < 0) {
269  return ErrnoError();
270  }
271  return cpus;
272 }
273 
274 
275 // Returns load struct with average system loads for the last
276 // 1, 5 and 15 minutes respectively.
277 // Load values should be interpreted as usual average loads from
278 // uptime(1).
280 {
281  double loadArray[3];
282  if (getloadavg(loadArray, 3) == -1) {
283  return ErrnoError("Failed to determine system load averages");
284  }
285 
286  Load load;
287  load.one = loadArray[0];
288  load.five = loadArray[1];
289  load.fifteen = loadArray[2];
290 
291  return load;
292 }
293 
294 
295 // Return the system information.
297 {
298  struct utsname name;
299 
300  if (::uname(&name) < 0) {
301  return ErrnoError();
302  }
303 
304  UTSInfo info;
305  info.sysname = name.sysname;
306  info.nodename = name.nodename;
307  info.release = name.release;
308  info.version = name.version;
309  info.machine = name.machine;
310  return info;
311 }
312 
313 
314 // Overload of os::pids for filtering by groups and sessions.
315 // A group / session id of 0 will fitler on the group / session ID
316 // of the calling process.
318 {
319  if (group.isNone() && session.isNone()) {
320  return os::pids();
321  } else if (group.isSome() && group.get() < 0) {
322  return Error("Invalid group");
323  } else if (session.isSome() && session.get() < 0) {
324  return Error("Invalid session");
325  }
326 
328 
329  if (processes.isError()) {
330  return Error(processes.error());
331  }
332 
333  // Obtain the calling process group / session ID when 0 is provided.
334  if (group.isSome() && group.get() == 0) {
335  group = getpgid(0);
336  }
337  if (session.isSome() && session.get() == 0) {
338  session = getsid(0);
339  }
340 
341  std::set<pid_t> result;
342  foreach (const Process& process, processes.get()) {
343  // Group AND Session (intersection).
344  if (group.isSome() && session.isSome()) {
345  if (group.get() == process.group &&
346  process.session.isSome() &&
347  session.get() == process.session.get()) {
348  result.insert(process.pid);
349  }
350  } else if (group.isSome() && group.get() == process.group) {
351  result.insert(process.pid);
352  } else if (session.isSome() && process.session.isSome() &&
353  session.get() == process.session.get()) {
354  result.insert(process.pid);
355  }
356  }
357 
358  return result;
359 }
360 
361 
362 // Creates a tar 'archive' with gzip compression, of the given 'path'.
363 inline Try<Nothing> tar(const std::string& path, const std::string& archive)
364 {
365  Try<std::string> tarOut =
366  os::shell("tar %s %s %s", "-czf", archive.c_str(), path.c_str());
367 
368  if (tarOut.isError()) {
369  return Error("Failed to archive " + path + ": " + tarOut.error());
370  }
371 
372  return Nothing();
373 }
374 
375 
376 // Return the OS release numbers.
378 {
379  Try<UTSInfo> info = uname();
380  if (info.isError()) {
381  return Error(info.error());
382  }
383 
384  int major, minor, patch = 0;
385 #ifndef __FreeBSD__
386  // TODO(karya): Replace sscanf with Version::parse() once Version
387  // starts supporting labels and build metadata.
388  if (::sscanf(
389  info.get().release.c_str(),
390  "%d.%d.%d",
391  &major,
392  &minor,
393  &patch) != 3) {
394  return Error("Failed to parse: " + info.get().release);
395  }
396 #else
397  // TODO(dforsyth): Handle FreeBSD patch versions (-pX).
398  if (::sscanf(info.get().release.c_str(), "%d.%d-%*s", &major, &minor) != 2) {
399  return Error("Failed to parse: " + info.get().release);
400  }
401 #endif
402  return Version(major, minor, patch);
403 }
404 
405 
407 {
408  return "/var";
409 }
410 
411 
412 inline Try<Nothing> dup2(int oldFd, int newFd)
413 {
414  while (::dup2(oldFd, newFd) == -1) {
415  if (errno == EINTR) {
416  continue;
417  } else {
418  return ErrnoError();
419  }
420  }
421  return Nothing();
422 }
423 
424 
425 inline Try<std::string> ptsname(int master)
426 {
427  // 'ptsname' is not thread safe. Therefore, we use mutex here to
428  // make this method thread safe.
429  // TODO(jieyu): Consider using ptsname_r for linux.
430  static std::mutex* mutex = new std::mutex;
431 
432  synchronized (mutex) {
433  const char* slavePath = ::ptsname(master);
434  if (slavePath == nullptr) {
435  return ErrnoError();
436  }
437  return slavePath;
438  }
439 }
440 
441 
442 inline Try<Nothing> setctty(int fd)
443 {
444  if (ioctl(fd, TIOCSCTTY, nullptr) == -1) {
445  return ErrnoError();
446  }
447 
448  return Nothing();
449 }
450 
451 
452 // Update the window size for
453 // the terminal represented by fd.
455  int fd,
456  unsigned short rows,
457  unsigned short columns)
458 {
459  struct winsize winsize;
460  winsize.ws_row = rows;
461  winsize.ws_col = columns;
462 
463  if (ioctl(fd, TIOCSWINSZ, &winsize) != 0) {
464  return ErrnoError();
465  }
466 
467  return Nothing();
468 }
469 
470 
471 // Returns a host-specific default for the `PATH` environment variable, based
472 // on the configuration of the host.
473 inline std::string host_default_path()
474 {
475  return "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
476 }
477 
478 } // namespace os {
479 
480 #endif // __STOUT_POSIX_OS_HPP__
Try< Nothing > dup2(int oldFd, int newFd)
Definition: os.hpp:412
Definition: nothing.hpp:16
Definition: errorbase.hpp:35
Try< std::string > patch(const std::string &s, const Diff &diff)
Definition: svn.hpp:157
Try< Nothing > chmod(const std::string &path, int mode)
Definition: os.hpp:194
Definition: try.hpp:34
Try< Nothing > sleep(const Duration &duration)
Definition: os.hpp:218
const pid_t group
Definition: process.hpp:55
Try< std::list< Process > > processes()
Definition: os.hpp:182
Try< Nothing > mknod(const std::string &path, mode_t mode, dev_t dev)
Definition: os.hpp:204
Result< ProcessStatus > status(pid_t pid)
Definition: proc.hpp:166
Definition: errorbase.hpp:49
const Option< pid_t > session
Definition: process.hpp:56
void setenv(const std::string &key, const std::string &value, bool overwrite=true)
Definition: os.hpp:157
void unsetenv(const std::string &key)
Definition: os.hpp:167
Definition: duration.hpp:32
Definition: result.hpp:40
std::string host_default_path()
Definition: os.hpp:473
char *** environmentp()
Definition: environment.hpp:88
bool isSome() const
Definition: option.hpp:115
std::string release
Definition: os.hpp:48
Definition: os.hpp:25
int execvp(const char *file, char *const argv[])
Definition: shell.hpp:192
std::string version
Definition: os.hpp:49
Try< Load > loadavg()
Definition: os.hpp:279
DWORD pid_t
Definition: windows.hpp:187
Definition: process.hpp:32
int mode_t
Definition: windows.hpp:183
Try< dev_t > dev(const std::string &path, const FollowSymlink follow=FollowSymlink::FOLLOW_SYMLINK)
Definition: stat.hpp:139
const pid_t pid
Definition: process.hpp:53
URI file(const std::string &path)
Creates a file URI with the given path on the local host.
Definition: file.hpp:33
Try< Nothing > utime(const std::string &path)
Definition: utime.hpp:32
Try< long > cpus()
Definition: os.hpp:264
Definition: duration.hpp:259
Try< Nothing > tar(const std::string &path, const std::string &archive)
Definition: os.hpp:363
std::string hstrerror(int err)=delete
Try< Nothing > setctty(int fd)
Definition: os.hpp:442
const T & get() const &
Definition: option.hpp:118
int random()
Definition: os.hpp:538
Try< Version > release()
Definition: os.hpp:377
double secs() const
Definition: duration.hpp:101
Result< pid_t > waitpid(pid_t pid, int *status, int options)
Definition: os.hpp:141
std::string sysname
Definition: os.hpp:46
Try< UTSInfo > uname()
Definition: os.hpp:296
static Try error(const E &e)
Definition: try.hpp:42
Try< std::string > shell(const std::string &fmt, const T &...t)
Runs a shell command with optional arguments.
Definition: shell.hpp:71
Result< Process > process(pid_t pid)
Definition: freebsd.hpp:30
Definition: grp.hpp:26
Definition: none.hpp:27
bool isError() const
Definition: try.hpp:71
std::string nodename
Definition: os.hpp:47
int execvpe(const std::string &command, const std::vector< std::string > &argv, const std::map< std::string, std::string > &envp)
Definition: shell.hpp:394
Definition: version.hpp:41
double fifteen
Definition: os.hpp:28
Try< mode_t > mode(const std::string &path, const FollowSymlink follow=FollowSymlink::FOLLOW_SYMLINK)
Definition: stat.hpp:126
bool isNone() const
Definition: option.hpp:116
Try< std::string > var()
Definition: os.hpp:406
Try< std::list< std::string > > glob(const std::string &pattern)
Definition: os.hpp:238
Try< std::set< pid_t > > pids()
Definition: freebsd.hpp:62
const T & get() const
Definition: try.hpp:73
double five
Definition: os.hpp:27
std::string machine
Definition: os.hpp:50
Try< Nothing > setWindowSize(int fd, unsigned short rows, unsigned short columns)
Definition: os.hpp:454
Definition: os.hpp:44
tm * gmtime_r(const time_t *timep, tm *result)
Definition: os.hpp:389
double one
Definition: os.hpp:26
Try< std::string > ptsname(int master)
Definition: os.hpp:425
char ** environment()
Definition: environment.hpp:66