• Skip to content
  • Skip to link menu
KDE 4.3 API Reference
  • KDE API Reference
  • kdelibs
  • Sitemap
  • Contact Us
 

KDECore

KShell Namespace Reference

Emulates some basic system shell functionality. More...

Enumerations

enum  Errors { NoError = 0, BadQuoting, FoundMeta }
enum  Option { NoOptions = 0, TildeExpand = 1, AbortOnMeta = 2 }

Functions

QString homeDir (const QString &user)
QString joinArgs (const QStringList &args)
QString quoteArg (const QString &arg)
QStringList splitArgs (const QString &cmd, Options flags=NoOptions, Errors *err=0)
QString tildeExpand (const QString &path)

Detailed Description

Emulates some basic system shell functionality.

See also:
KStringHandler

Enumeration Type Documentation

enum KShell::Errors

Status codes from splitArgs().

Enumerator:
NoError 

Success.

BadQuoting 

Indicates a parsing error, like an unterminated quoted string.

FoundMeta 

The AbortOnMeta flag was set and an unhandled shell meta character was encoutered.

Definition at line 84 of file kshell.h.

enum KShell::Option

Flags for splitArgs().

Enumerator:
NoOptions 
TildeExpand 

Perform tilde expansion.

On Windows, this flag is ignored, as the Windows shell has no equivalent functionality.

AbortOnMeta 

Put the parser into full shell mode and bail out if a too complex construct is encoutered.

A particular purpose of this flag is finding out whether the command line being splitted would be executable directly (via KProcess::setProgram()) or whether it needs to be run through a real shell (via KProcess::setShellCommand()). Note, however, that shell builtins are not recognized - you need to do that yourself (compare with a list of known commands or verify that an executable exists for the named command).

Meta characters that cause a bail-out are the command separators semicolon and ampersand, the redirection symbols less-than, greater-than and the pipe symbol and the grouping symbols opening and closing parentheses.

Further meta characters on *NIX are the grouping symbols opening and closing braces, the command substitution symbol backquote, the generic substitution symbol dollar (if not followed by an apostrophe), the wildcards asterisk and question mark and the comment symbol hash mark. Additionally, a variable assignment in the first word is recognized.

A further meta character on Windows is the environment variable expansion symbol percent. Occurrences of %PERCENT_SIGN% as inserted by quoteArg() are converted back and cause no bail-out, though.

Definition at line 39 of file kshell.h.


Function Documentation

QString KShell::homeDir ( const QString &  user  ) 

Definition at line 29 of file kshell.cpp.

QString KShell::joinArgs ( const QStringList &  args  ) 

Quotes and joins args together according to system shell rules.

If the output is fed back into splitArgs(), the AbortOnMeta flag needs to be used on Windows. On *NIX, no such requirement exists.

See quoteArg() for more info.

Parameters:
args a list of strings to quote and join
Returns:
a command suitable for shell execution

Definition at line 38 of file kshell.cpp.

QString KShell::quoteArg ( const QString &  arg  ) 

Quotes arg according to system shell rules.

This function can be used to quote an argument string such that the shell processes it properly. This is e.g. necessary for user-provided file names which may contain spaces or quotes. It also prevents expansion of wild cards and environment variables.

On *NIX, the output is POSIX shell compliant. On Windows, it is compliant with the argument splitting code of the Microsoft C runtime and the cmd shell used together. Occurrences of the percent sign are replaced with %PERCENT_SIGN% to prevent spurious variable expansion; related KDE functions are prepared for this.

Parameters:
arg the argument to quote
Returns:
the quoted argument

Definition at line 276 of file kshell_unix.cpp.

QStringList KShell::splitArgs ( const QString &  cmd,
Options  flags = NoOptions,
Errors *  err = 0 
)

Splits cmd according to system shell word splitting and quoting rules.

Can optionally perform tilde expansion and/or abort if it finds shell meta characters it cannot process.

On *NIX the behavior is based on the POSIX shell and bash:

  • Whitespace splits tokens
  • The backslash quotes the following character
  • A string enclosed in single quotes is not split. No shell meta characters are interpreted.
  • A string enclosed in double quotes is not split. Within the string, the backslash quotes shell meta characters - if it is followed by a "meaningless" character, the backslash is output verbatim.
  • A string enclosed in $'' is not split. Within the string, the backslash has a similar meaning to the one in C strings. Consult the bash manual for more information.

On Windows, the behavior is defined by the Microsoft C runtime. Qt and many other implementations comply with this standard, but many do not.

  • Whitespace splits tokens
  • A string enclosed in double quotes is not split
    • 2N double quotes within a quoted string yield N literal quotes. This is not documented on MSDN.
  • Backslashes have special semantics iff they are followed by a double quote:
    • 2N backslashes + double quote => N backslashes and begin/end quoting
    • 2N+1 backslashes + double quote => N backslashes + literal quote

If AbortOnMeta is used on Windows, this function applies cmd shell semantics before proceeding with word splitting:

  • Cmd ignores all special chars between double quotes. Note that the quotes are not removed at this stage - the tokenization rules described above still apply.
  • The circumflex is the escape char for everything including itself.
Parameters:
cmd the command to split
flags operation flags, see Option
err if not NULL, a status code will be stored at the pointer target, see Errors
Returns:
a list of unquoted words or an empty list if an error occurred

Definition at line 70 of file kshell_unix.cpp.

QString KShell::tildeExpand ( const QString &  path  ) 

Performs tilde expansion on path.

Interprets "~/path" and "~user/path". If the path starts with an escaped tilde ("\~" on UNIX, "^~" on Windows), the escape char is removed and the path is returned as is.

Parameters:
path the path to tilde-expand
Returns:
the expanded path

Definition at line 55 of file kshell.cpp.

KDECore

Skip menu "KDECore"
  • Main Page
  • Modules
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

kdelibs

Skip menu "kdelibs"
  • DNSSD
  • Interfaces
  •   KHexEdit
  •   KMediaPlayer
  •   KSpeech
  •   KTextEditor
  • Kate
  • kconf_update
  • KDE3Support
  •   KUnitTest
  • KDECore
  • KDED
  • KDEsu
  • KDEUI
  • KDocTools
  • KFile
  • KHTML
  • KImgIO
  • KInit
  • kio
  • KIOSlave
  • KJS
  •   KJS-API
  •   WTF
  • kjsembed
  • KNewStuff
  • KParts
  • KPty
  • Kross
  • KUtils
  • Nepomuk
  • Plasma
  • Solid
  • Sonnet
  • ThreadWeaver
Generated for kdelibs by doxygen 1.6.1
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal