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 // Erases the value associated with the specified key from the set of
174 // environment variables.
175 inline void eraseenv(const std::string& key)
176 {
177  char * value = ::getenv(key.c_str());
178 
179  // Erase the old value so that on Linux it can't be inspected through
180  // /proc/$pid/environ.
181  if (value) {
182  ::memset(value, '\0', ::strlen(value));
183  }
184 
185  ::unsetenv(key.c_str());
186 }
187 
188 
189 // This function is a portable version of execvpe ('p' means searching
190 // executable from PATH and 'e' means setting environments). We add
191 // this function because it is not available on all systems.
192 //
193 // NOTE: This function is not thread safe. It is supposed to be used
194 // only after fork (when there is only one thread). This function is
195 // async signal safe.
196 inline int execvpe(const char* file, char** argv, char** envp)
197 {
198  char** saved = os::raw::environment();
199 
200  *os::raw::environmentp() = envp;
201 
202  int result = execvp(file, argv);
203 
204  *os::raw::environmentp() = saved;
205 
206  return result;
207 }
208 
209 
210 inline Try<Nothing> chmod(const std::string& path, int mode)
211 {
212  if (::chmod(path.c_str(), mode) < 0) {
213  return ErrnoError();
214  }
215 
216  return Nothing();
217 }
218 
219 
221  const std::string& path,
222  mode_t mode,
223  dev_t dev)
224 {
225  if (::mknod(path.c_str(), mode, dev) < 0) {
226  return ErrnoError();
227  }
228 
229  return Nothing();
230 }
231 
232 
233 // Suspends execution for the given duration.
234 inline Try<Nothing> sleep(const Duration& duration)
235 {
236  timespec remaining;
237  remaining.tv_sec = static_cast<long>(duration.secs());
238  remaining.tv_nsec =
239  static_cast<long>((duration - Seconds(remaining.tv_sec)).ns());
240 
241  while (nanosleep(&remaining, &remaining) == -1) {
242  if (errno == EINTR) {
243  continue;
244  } else {
245  return ErrnoError();
246  }
247  }
248 
249  return Nothing();
250 }
251 
252 
253 // Returns the list of files that match the given (shell) pattern.
254 inline Try<std::list<std::string>> glob(const std::string& pattern)
255 {
256  glob_t g;
257  int status = ::glob(pattern.c_str(), GLOB_NOSORT, nullptr, &g);
258 
259  std::list<std::string> result;
260 
261  if (status != 0) {
262  if (status == GLOB_NOMATCH) {
263  return result; // Empty list.
264  } else {
265  return ErrnoError();
266  }
267  }
268 
269  for (size_t i = 0; i < g.gl_pathc; ++i) {
270  result.push_back(g.gl_pathv[i]);
271  }
272 
273  globfree(&g); // Best-effort free of dynamically allocated memory.
274 
275  return result;
276 }
277 
278 
279 // Returns the total number of cpus (cores).
280 inline Try<long> cpus()
281 {
282  long cpus = sysconf(_SC_NPROCESSORS_ONLN);
283 
284  if (cpus < 0) {
285  return ErrnoError();
286  }
287  return cpus;
288 }
289 
290 
291 // Returns load struct with average system loads for the last
292 // 1, 5 and 15 minutes respectively.
293 // Load values should be interpreted as usual average loads from
294 // uptime(1).
296 {
297  double loadArray[3];
298  if (getloadavg(loadArray, 3) == -1) {
299  return ErrnoError("Failed to determine system load averages");
300  }
301 
302  Load load;
303  load.one = loadArray[0];
304  load.five = loadArray[1];
305  load.fifteen = loadArray[2];
306 
307  return load;
308 }
309 
310 
311 // Return the system information.
313 {
314  struct utsname name;
315 
316  if (::uname(&name) < 0) {
317  return ErrnoError();
318  }
319 
320  UTSInfo info;
321  info.sysname = name.sysname;
322  info.nodename = name.nodename;
323  info.release = name.release;
324  info.version = name.version;
325  info.machine = name.machine;
326  return info;
327 }
328 
329 
330 // Overload of os::pids for filtering by groups and sessions.
331 // A group / session id of 0 will fitler on the group / session ID
332 // of the calling process.
334 {
335  if (group.isNone() && session.isNone()) {
336  return os::pids();
337  } else if (group.isSome() && group.get() < 0) {
338  return Error("Invalid group");
339  } else if (session.isSome() && session.get() < 0) {
340  return Error("Invalid session");
341  }
342 
344 
345  if (processes.isError()) {
346  return Error(processes.error());
347  }
348 
349  // Obtain the calling process group / session ID when 0 is provided.
350  if (group.isSome() && group.get() == 0) {
351  group = getpgid(0);
352  }
353  if (session.isSome() && session.get() == 0) {
354  session = getsid(0);
355  }
356 
357  std::set<pid_t> result;
358  foreach (const Process& process, processes.get()) {
359  // Group AND Session (intersection).
360  if (group.isSome() && session.isSome()) {
361  if (group.get() == process.group &&
362  process.session.isSome() &&
363  session.get() == process.session.get()) {
364  result.insert(process.pid);
365  }
366  } else if (group.isSome() && group.get() == process.group) {
367  result.insert(process.pid);
368  } else if (session.isSome() && process.session.isSome() &&
369  session.get() == process.session.get()) {
370  result.insert(process.pid);
371  }
372  }
373 
374  return result;
375 }
376 
377 
378 // Creates a tar 'archive' with gzip compression, of the given 'path'.
379 inline Try<Nothing> tar(const std::string& path, const std::string& archive)
380 {
381  Try<std::string> tarOut =
382  os::shell("tar %s %s %s", "-czf", archive.c_str(), path.c_str());
383 
384  if (tarOut.isError()) {
385  return Error("Failed to archive " + path + ": " + tarOut.error());
386  }
387 
388  return Nothing();
389 }
390 
391 
392 // Return the OS release numbers.
394 {
395  Try<UTSInfo> info = uname();
396  if (info.isError()) {
397  return Error(info.error());
398  }
399 
400  int major, minor, patch = 0;
401 #ifndef __FreeBSD__
402  // TODO(karya): Replace sscanf with Version::parse() once Version
403  // starts supporting labels and build metadata.
404  if (::sscanf(
405  info->release.c_str(),
406  "%d.%d.%d",
407  &major,
408  &minor,
409  &patch) != 3) {
410  return Error("Failed to parse: " + info->release);
411  }
412 #else
413  // TODO(dforsyth): Handle FreeBSD patch versions (-pX).
414  if (::sscanf(info->release.c_str(), "%d.%d-%*s", &major, &minor) != 2) {
415  return Error("Failed to parse: " + info->release);
416  }
417 #endif
418  return Version(major, minor, patch);
419 }
420 
421 
423 {
424  return "/var";
425 }
426 
427 
428 inline Try<Nothing> dup2(int oldFd, int newFd)
429 {
430  while (::dup2(oldFd, newFd) == -1) {
431  if (errno == EINTR) {
432  continue;
433  } else {
434  return ErrnoError();
435  }
436  }
437  return Nothing();
438 }
439 
440 
442 {
443  // 'ptsname' is not thread safe. Therefore, we use mutex here to
444  // make this method thread safe.
445  // TODO(jieyu): Consider using ptsname_r for linux.
446  static std::mutex* mutex = new std::mutex;
447 
448  synchronized (mutex) {
449  const char* slavePath = ::ptsname(master);
450  if (slavePath == nullptr) {
451  return ErrnoError();
452  }
453  return slavePath;
454  }
455 }
456 
457 
458 inline Try<Nothing> setctty(int fd)
459 {
460  if (ioctl(fd, TIOCSCTTY, nullptr) == -1) {
461  return ErrnoError();
462  }
463 
464  return Nothing();
465 }
466 
467 
468 // Update the window size for
469 // the terminal represented by fd.
471  int fd,
472  unsigned short rows,
473  unsigned short columns)
474 {
475  struct winsize winsize;
476  winsize.ws_row = rows;
477  winsize.ws_col = columns;
478 
479  if (ioctl(fd, TIOCSWINSZ, &winsize) != 0) {
480  return ErrnoError();
481  }
482 
483  return Nothing();
484 }
485 
486 
487 // Returns a host-specific default for the `PATH` environment variable, based
488 // on the configuration of the host.
489 inline std::string host_default_path()
490 {
491  return "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
492 }
493 
494 } // namespace os {
495 
496 #endif // __STOUT_POSIX_OS_HPP__
Try< Nothing > dup2(int oldFd, int newFd)
Definition: os.hpp:428
Definition: path.hpp:26
Definition: nothing.hpp:16
Definition: errorbase.hpp:35
T & get()&
Definition: try.hpp:73
Try< std::string > patch(const std::string &s, const Diff &diff)
Definition: svn.hpp:157
Definition: master.hpp:27
Try< Nothing > chmod(const std::string &path, int mode)
Definition: os.hpp:210
Definition: check.hpp:33
Try< Nothing > sleep(const Duration &duration)
Definition: os.hpp:234
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:220
Result< ProcessStatus > status(pid_t pid)
Definition: proc.hpp:166
Definition: errorbase.hpp:49
Definition: posix_signalhandler.hpp:23
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: check.hpp:30
std::string host_default_path()
Definition: os.hpp:489
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:195
std::string version
Definition: os.hpp:49
Try< Load > loadavg()
Definition: os.hpp:295
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:280
Definition: duration.hpp:207
Try< Nothing > tar(const std::string &path, const std::string &archive)
Definition: os.hpp:379
std::string hstrerror(int err)=delete
Try< Nothing > setctty(int fd)
Definition: os.hpp:458
const T & get() const &
Definition: option.hpp:118
Option< std::string > getenv(const std::string &key)
Definition: getenv.hpp:29
int random()
Definition: os.hpp:546
Try< Version > release()
Definition: os.hpp:393
double secs() const
Definition: duration.hpp:49
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:312
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:73
Definition: grp.hpp:26
Definition: none.hpp:27
bool isError() const
Definition: try.hpp:71
std::string nodename
Definition: os.hpp:47
Definition: ns.hpp:81
Definition: executor.hpp:47
void eraseenv(const std::string &key)
Definition: os.hpp:175
int execvpe(const std::string &command, const std::vector< std::string > &argv, const std::map< std::string, std::string > &envp)
Definition: shell.hpp:427
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:422
Try< std::list< std::string > > glob(const std::string &pattern)
Definition: os.hpp:254
Try< std::set< pid_t > > pids()
Definition: freebsd.hpp:62
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:470
Definition: os.hpp:44
tm * gmtime_r(const time_t *timep, tm *result)
Definition: os.hpp:397
double one
Definition: os.hpp:26
Try< std::string > ptsname(int master)
Definition: os.hpp:441
char ** environment()
Definition: environment.hpp:66