parameters: (self, cmd, check_return=False, cwd=None, env=None,
                        as_root=False, single_line=False, large_output=False,
                        raw_output=False, timeout=None, retries=None)
docstring: Run an ADB shell command.
  
      The command to run |cmd| should be a sequence of program arguments or else
      a single string.
  
      When |cmd| is a sequence, it is assumed to contain the name of the command
      to run followed by its arguments. In this case, arguments are passed to the
      command exactly as given, without any further processing by the shell. This
      allows to easily pass arguments containing spaces or special characters
      without having to worry about getting quoting right. Whenever possible, it
      is recomended to pass |cmd| as a sequence.
  
      When |cmd| is given as a string, it will be interpreted and run by the
      shell on the device.
  
      This behaviour is consistent with that of command runners in cmd_helper as
      well as Python's own subprocess.Popen.
  
      TODO(perezju) Change the default of |check_return| to True when callers
        have switched to the new behaviour.
  
      Args:
        cmd: A string with the full command to run on the device, or a sequence
          containing the command and its arguments.
        check_return: A boolean indicating whether or not the return code should
          be checked.
        cwd: The device directory in which the command should be run.
        env: The environment variables with which the command should be run.
        as_root: A boolean indicating whether the shell command should be run
          with root privileges.
        single_line: A boolean indicating if only a single line of output is
          expected.
        large_output: Uses a work-around for large shell command output. Without
          this large output will be truncated.
        raw_output: Whether to only return the raw output
            (no splitting into lines).
        timeout: timeout in seconds
        retries: number of retries
  
      Returns:
        If single_line is False, the output of the command as a list of lines,
        otherwise, a string with the unique line of output emmited by the command
        (with the optional newline at the end stripped).
  
      Raises:
        AdbCommandFailedError if check_return is True and the exit code of
          the command run on the device is non-zero.
        CommandFailedError if single_line is True but the output contains two or
          more lines.
        CommandTimeoutError on timeout.
        DeviceUnreachableError on missing device.
docstring_summary: Run an ADB shell command.
docstring_tokens: Run an ADB shell command .
function: def RunShellCommand(self, cmd, check_return=False, cwd=None, env=None,
                        as_root=False, single_line=False, large_output=False,
                        raw_output=False, timeout=None, retries=None):
      """Run an ADB shell command.
  
      The command to run |cmd| should be a sequence of program arguments or else
      a single string.
  
      When |cmd| is a sequence, it is assumed to contain the name of the command
      to run followed by its arguments. In this case, arguments are passed to the
      command exactly as given, without any further processing by the shell. This
      allows to easily pass arguments containing spaces or special characters
      without having to worry about getting quoting right. Whenever possible, it
      is recomended to pass |cmd| as a sequence.
  
      When |cmd| is given as a string, it will be interpreted and run by the
      shell on the device.
  
      This behaviour is consistent with that of command runners in cmd_helper as
      well as Python's own subprocess.Popen.
  
      TODO(perezju) Change the default of |check_return| to True when callers
        have switched to the new behaviour.
  
      Args:
        cmd: A string with the full command to run on the device, or a sequence
          containing the command and its arguments.
        check_return: A boolean indicating whether or not the return code should
          be checked.
        cwd: The device directory in which the command should be run.
        env: The environment variables with which the command should be run.
        as_root: A boolean indicating whether the shell command should be run
          with root privileges.
        single_line: A boolean indicating if only a single line of output is
          expected.
        large_output: Uses a work-around for large shell command output. Without
          this large output will be truncated.
        raw_output: Whether to only return the raw output
            (no splitting into lines).
        timeout: timeout in seconds
        retries: number of retries
  
      Returns:
        If single_line is False, the output of the command as a list of lines,
        otherwise, a string with the unique line of output emmited by the command
        (with the optional newline at the end stripped).
  
      Raises:
        AdbCommandFailedError if check_return is True and the exit code of
          the command run on the device is non-zero.
        CommandFailedError if single_line is True but the output contains two or
          more lines.
        CommandTimeoutError on timeout.
        DeviceUnreachableError on missing device.
      """
      def env_quote(key, value):
        if not DeviceUtils._VALID_SHELL_VARIABLE.match(key):
          raise KeyError('Invalid shell variable name %r' % key)
        # using double quotes here to allow interpolation of shell variables
        return '%s=%s' % (key, cmd_helper.DoubleQuote(value))
  
      def run(cmd):
        return self.adb.Shell(cmd)
  
      def handle_check_return(cmd):
        try:
          return run(cmd)
        except device_errors.AdbCommandFailedError as exc:
          if check_return:
            raise
          else:
            return exc.output
  
      def handle_large_command(cmd):
        if len(cmd) < self._MAX_ADB_COMMAND_LENGTH:
          return handle_check_return(cmd)
        else:
          with device_temp_file.DeviceTempFile(self.adb, suffix='.sh') as script:
            self._WriteFileWithPush(script.name, cmd)
            logging.info('Large shell command will be run from file: %s ...',
                         cmd[:self._MAX_ADB_COMMAND_LENGTH])
            return handle_check_return('sh %s' % script.name_quoted)
  
      def handle_large_output(cmd, large_output_mode):
        if large_output_mode:
          with device_temp_file.DeviceTempFile(self.adb) as large_output_file:
            cmd = '( %s )>%s' % (cmd, large_output_file.name)
            logging.debug('Large output mode enabled. Will write output to '
                          'device and read results from file.')
            handle_large_command(cmd)
            return self.ReadFile(large_output_file.name, force_pull=True)
        else:
          try:
            return handle_large_command(cmd)
          except device_errors.AdbCommandFailedError as exc:
            if exc.status is None:
              logging.error(_FormatPartialOutputError(exc.output))
              logging.warning('Attempting to run in large_output mode.')
              logging.warning('Use RunShellCommand(..., large_output=True) for '
                              'shell commands that expect a lot of output.')
              return handle_large_output(cmd, True)
            else:
              raise
  
      if not isinstance(cmd, basestring):
        cmd = ' '.join(cmd_helper.SingleQuote(s) for s in cmd)
      if env:
        env = ' '.join(env_quote(k, v) for k, v in env.iteritems())
        cmd = '%s %s' % (env, cmd)
      if cwd:
        cmd = 'cd %s && %s' % (cmd_helper.SingleQuote(cwd), cmd)
      if as_root and self.NeedsSU():
        # "su -c sh -c" allows using shell features in |cmd|
        cmd = self._Su('sh -c %s' % cmd_helper.SingleQuote(cmd))
  
      output = handle_large_output(cmd, large_output)
  
      if raw_output:
        return output
  
      output = output.splitlines()
      if single_line:
        if not output:
          return ''
        elif len(output) == 1:
          return output[0]
        else:
          msg = 'one line of output was expected, but got: %s'
          raise device_errors.CommandFailedError(msg % output, str(self))
      else:
        return output
function_tokens: def RunShellCommand ( self , cmd , check_return = False , cwd = None , env = None , as_root = False , single_line = False , large_output = False , raw_output = False , timeout = None , retries = None ) : def env_quote ( key , value ) : if not DeviceUtils . _VALID_SHELL_VARIABLE . match ( key ) : raise KeyError ( 'Invalid shell variable name %r' % key ) # using double quotes here to allow interpolation of shell variables return '%s=%s' % ( key , cmd_helper . DoubleQuote ( value ) ) def run ( cmd ) : return self . adb . Shell ( cmd ) def handle_check_return ( cmd ) : try : return run ( cmd ) except device_errors . AdbCommandFailedError as exc : if check_return : raise else : return exc . output def handle_large_command ( cmd ) : if len ( cmd ) < self . _MAX_ADB_COMMAND_LENGTH : return handle_check_return ( cmd ) else : with device_temp_file . DeviceTempFile ( self . adb , suffix = '.sh' ) as script : self . _WriteFileWithPush ( script . name , cmd ) logging . info ( 'Large shell command will be run from file: %s ...' , cmd [ : self . _MAX_ADB_COMMAND_LENGTH ] ) return handle_check_return ( 'sh %s' % script . name_quoted ) def handle_large_output ( cmd , large_output_mode ) : if large_output_mode : with device_temp_file . DeviceTempFile ( self . adb ) as large_output_file : cmd = '( %s )>%s' % ( cmd , large_output_file . name ) logging . debug ( 'Large output mode enabled. Will write output to ' 'device and read results from file.' ) handle_large_command ( cmd ) return self . ReadFile ( large_output_file . name , force_pull = True ) else : try : return handle_large_command ( cmd ) except device_errors . AdbCommandFailedError as exc : if exc . status is None : logging . error ( _FormatPartialOutputError ( exc . output ) ) logging . warning ( 'Attempting to run in large_output mode.' ) logging . warning ( 'Use RunShellCommand(..., large_output=True) for ' 'shell commands that expect a lot of output.' ) return handle_large_output ( cmd , True ) else : raise if not isinstance ( cmd , basestring ) : cmd = ' ' . join ( cmd_helper . SingleQuote ( s ) for s in cmd ) if env : env = ' ' . join ( env_quote ( k , v ) for k , v in env . iteritems ( ) ) cmd = '%s %s' % ( env , cmd ) if cwd : cmd = 'cd %s && %s' % ( cmd_helper . SingleQuote ( cwd ) , cmd ) if as_root and self . NeedsSU ( ) : # "su -c sh -c" allows using shell features in |cmd| cmd = self . _Su ( 'sh -c %s' % cmd_helper . SingleQuote ( cmd ) ) output = handle_large_output ( cmd , large_output ) if raw_output : return output output = output . splitlines ( ) if single_line : if not output : return '' elif len ( output ) == 1 : return output [ 0 ] else : msg = 'one line of output was expected, but got: %s' raise device_errors . CommandFailedError ( msg % output , str ( self ) ) else : return output