DumpstateUtil.h revision bda15a00929b836a53bf03473b1ec36285e5944b 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16#ifndef FRAMEWORK_NATIVE_CMD_DUMPSTATE_UTIL_H_
17#define FRAMEWORK_NATIVE_CMD_DUMPSTATE_UTIL_H_
18
19/*
20 * Defines the Linux user that should be executing a command.
21 */
22enum RootMode {
23    /* Explicitly change the `uid` and `gid` to be `shell`.*/
24    DROP_ROOT,
25    /* Don't change the `uid` and `gid`. */
26    DONT_DROP_ROOT,
27    /* Prefix the command with `/PATH/TO/su root`. Won't work non user builds. */
28    SU_ROOT
29};
30
31/*
32 * Defines what should happen with the `stdout` stream of a command.
33 */
34enum StdoutMode {
35    /* Don't change `stdout`. */
36    NORMAL_STDOUT,
37    /* Redirect `stdout` to `stderr`. */
38    REDIRECT_TO_STDERR
39};
40
41/*
42 * Value object used to set command options.
43 *
44 * Typically constructed using a builder with chained setters. Examples:
45 *
46 *  CommandOptions::WithTimeout(20).AsRoot().Build();
47 *  CommandOptions::WithTimeout(10).Always().RedirectStderr().Build();
48 *
49 * Although the builder could be used to dynamically set values. Example:
50 *
51 *  CommandOptions::CommandOptionsBuilder options =
52 *  CommandOptions::WithTimeout(10);
53 *  if (!is_user_build()) {
54 *    options.AsRoot();
55 *  }
56 *  RunCommand("command", {"args"}, options.Build());
57 */
58class CommandOptions {
59  private:
60    class CommandOptionsValues {
61      private:
62        CommandOptionsValues(int64_t timeout);
63
64        int64_t timeout_;
65        bool always_;
66        RootMode root_mode_;
67        StdoutMode stdout_mode_;
68        std::string logging_message_;
69
70        friend class CommandOptions;
71        friend class CommandOptionsBuilder;
72    };
73
74    CommandOptions(const CommandOptionsValues& values);
75
76    const CommandOptionsValues values;
77
78  public:
79    class CommandOptionsBuilder {
80      public:
81        /* Sets the command to always run, even on `dry-run` mode. */
82        CommandOptionsBuilder& Always();
83        /* Sets the command's RootMode as `SU_ROOT` */
84        CommandOptionsBuilder& AsRoot();
85        /* Sets the command's RootMode as `DROP_ROOT` */
86        CommandOptionsBuilder& DropRoot();
87        /* Sets the command's StdoutMode `REDIRECT_TO_STDERR` */
88        CommandOptionsBuilder& RedirectStderr();
89        /* When not empty, logs a message before executing the command.
90         * Must contain a `%s`, which will be replaced by the full command line, and end on `\n`. */
91        CommandOptionsBuilder& Log(const std::string& message);
92        /* Builds the command options. */
93        CommandOptions Build();
94
95      private:
96        CommandOptionsBuilder(int64_t timeout);
97        CommandOptionsValues values;
98        friend class CommandOptions;
99    };
100
101    /** Gets the command timeout, in seconds. */
102    int64_t Timeout() const;
103    /* Checks whether the command should always be run, even on dry-run mode. */
104    bool Always() const;
105    /** Gets the RootMode of the command. */
106    RootMode RootMode() const;
107    /** Gets the StdoutMode of the command. */
108    StdoutMode StdoutMode() const;
109    /** Gets the logging message header, it any. */
110    std::string LoggingMessage() const;
111
112    /** Creates a builder with the requied timeout. */
113    static CommandOptionsBuilder WithTimeout(int64_t timeout);
114
115    // Common options.
116    static CommandOptions DEFAULT;
117    static CommandOptions AS_ROOT_5;
118    static CommandOptions AS_ROOT_10;
119    static CommandOptions AS_ROOT_20;
120};
121
122/*
123 * Forks a command, waits for it to finish, and returns its status.
124 *
125 * |fd| file descriptor that receives the command's 'stdout'.
126 * |full_command| array containing the command (first entry) and its arguments.
127 * Must contain at least one element.
128 * |options| optional argument defining the command's behavior.
129 * |description| optional description of the command to be used on log messages. If empty,
130 * the command path (without arguments) will be used instead.
131 */
132int RunCommandToFd(int fd, const std::vector<const char*>& full_command,
133                   const CommandOptions& options = CommandOptions::DEFAULT,
134                   const std::string& description = "");
135
136/*
137 * Dumps the contents of a file into a file descriptor.
138 *
139 * |fd| file descriptor where the file is dumped into.
140 * |path| location of the file to be dumped.
141 */
142int DumpFileToFd(int fd, const std::string& path);
143
144#endif  // FRAMEWORK_NATIVE_CMD_DUMPSTATE_UTIL_H_
145