1 //===-- Host.h --------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Host_h_
11 #define liblldb_Host_h_
12 #if defined(__cplusplus)
19 #include "lldb/lldb-private.h"
20 #include "lldb/Core/StringList.h"
21 #include "lldb/Host/File.h"
23 namespace lldb_private {
25 //----------------------------------------------------------------------
26 /// @class Host Host.h "lldb/Host/Host.h"
27 /// @brief A class that provides host computer information.
29 /// Host is a class that answers information about the host operating
31 //----------------------------------------------------------------------
35 typedef bool (*MonitorChildProcessCallback) (void *callback_baton,
38 int signal, // Zero for no signal
39 int status); // Exit value of process if signal is zero
41 //------------------------------------------------------------------
42 /// Start monitoring a child process.
44 /// Allows easy monitoring of child processes. \a callback will be
45 /// called when the child process exits or if it gets a signal. The
46 /// callback will only be called with signals if \a monitor_signals
47 /// is \b true. \a callback will usually be called from another
48 /// thread so the callback function must be thread safe.
50 /// When the callback gets called, the return value indicates if
51 /// minotoring should stop. If \b true is returned from \a callback
52 /// the information will be removed. If \b false is returned then
53 /// monitoring will continue. If the child process exits, the
54 /// monitoring will automatically stop after the callback returned
55 /// ragardless of the callback return value.
57 /// @param[in] callback
58 /// A function callback to call when a child receives a signal
59 /// (if \a monitor_signals is true) or a child exits.
61 /// @param[in] callback_baton
62 /// A void * of user data that will be pass back when
63 /// \a callback is called.
66 /// The process ID of a child process to monitor, -1 for all
69 /// @param[in] monitor_signals
70 /// If \b true the callback will get called when the child
71 /// process gets a signal. If \b false, the callback will only
72 /// get called if the child process exits.
75 /// A thread handle that can be used to cancel the thread that
76 /// was spawned to monitor \a pid.
78 /// @see static void Host::StopMonitoringChildProcess (uint32_t)
79 //------------------------------------------------------------------
81 StartMonitoringChildProcess (MonitorChildProcessCallback callback,
84 bool monitor_signals);
86 //------------------------------------------------------------------
87 /// Get the host page size.
90 /// The size in bytes of a VM page on the host system.
91 //------------------------------------------------------------------
95 //------------------------------------------------------------------
96 /// Returns the endianness of the host system.
99 /// Returns the endianness of the host system as a lldb::ByteOrder
101 //------------------------------------------------------------------
102 static lldb::ByteOrder
105 //------------------------------------------------------------------
106 /// Returns the number of CPUs on this current host.
109 /// Number of CPUs on this current host, or zero if the number
110 /// of CPUs can't be determined on this host.
111 //------------------------------------------------------------------
116 GetOSVersion (uint32_t &major,
121 GetOSBuildString (std::string &s);
124 GetOSKernelDescription (std::string &s);
127 GetHostname (std::string &s);
130 GetUserName (uint32_t uid, std::string &user_name);
133 GetGroupName (uint32_t gid, std::string &group_name);
142 GetEffectiveUserID ();
145 GetEffectiveGroupID ();
155 SystemLog (SystemLogType type, const char *format, ...) __attribute__ ((format (printf, 2, 3)));
158 SystemLog (SystemLogType type, const char *format, va_list args);
160 //------------------------------------------------------------------
161 /// Gets the host architecture.
164 /// A const architecture object that represents the host
166 //------------------------------------------------------------------
167 enum SystemDefaultArchitecture
169 eSystemDefaultArchitecture, // The overall default architecture that applications will run on this host
170 eSystemDefaultArchitecture32, // If this host supports 32 bit programs, return the default 32 bit arch
171 eSystemDefaultArchitecture64 // If this host supports 64 bit programs, return the default 64 bit arch
174 static const ArchSpec &
175 GetArchitecture (SystemDefaultArchitecture arch_kind = eSystemDefaultArchitecture);
177 //------------------------------------------------------------------
178 /// Gets the host vendor string.
181 /// A const string object containing the host vendor name.
182 //------------------------------------------------------------------
183 static const ConstString &
186 //------------------------------------------------------------------
187 /// Gets the host Operating System (OS) string.
190 /// A const string object containing the host OS name.
191 //------------------------------------------------------------------
192 static const ConstString &
195 //------------------------------------------------------------------
196 /// Gets the host target triple as a const string.
199 /// A const string object containing the host target triple.
200 //------------------------------------------------------------------
201 static const ConstString &
204 //------------------------------------------------------------------
205 /// Gets the name of the distribution (i.e. distributor id).
207 /// On Linux, this will return the equivalent of lsb_release -i.
208 /// Android will return 'android'. Other systems may return
212 /// A ConstString reference containing the OS distribution id.
213 /// The return string will be all lower case, with whitespace
214 /// replaced with underscores. The return string will be
215 /// empty (result.AsCString() will return NULL) if the distribution
216 /// cannot be obtained.
217 //------------------------------------------------------------------
218 static const ConstString &
219 GetDistributionId ();
221 //------------------------------------------------------------------
222 /// Get the process ID for the calling process.
225 /// The process ID for the current process.
226 //------------------------------------------------------------------
228 GetCurrentProcessID ();
231 Kill(lldb::pid_t pid, int signo);
233 //------------------------------------------------------------------
234 /// Get the thread ID for the calling thread in the current process.
237 /// The thread ID for the calling thread in the current process.
238 //------------------------------------------------------------------
240 GetCurrentThreadID ();
242 //------------------------------------------------------------------
243 /// Get the thread token (the one returned by ThreadCreate when the thread was created) for the
244 /// calling thread in the current process.
247 /// The thread token for the calling thread in the current process.
248 //------------------------------------------------------------------
249 static lldb::thread_t
253 GetSignalAsCString (int signo);
257 //------------------------------------------------------------------
258 /// Host specific thread created function call.
260 /// This function call lets the current host OS do any thread
261 /// specific initialization that it needs, including naming the
262 /// thread. No cleanup routine is exptected to be called
265 /// The current thread's name in the current process.
266 //------------------------------------------------------------------
268 ThreadCreated (const char *name);
270 static lldb::thread_t
271 ThreadCreate (const char *name,
272 lldb::thread_func_t function,
273 lldb::thread_arg_t thread_arg,
277 ThreadCancel (lldb::thread_t thread,
281 ThreadDetach (lldb::thread_t thread,
284 ThreadJoin (lldb::thread_t thread,
285 lldb::thread_result_t *thread_result_ptr,
288 typedef void (*ThreadLocalStorageCleanupCallback) (void *p);
290 static lldb::thread_key_t
291 ThreadLocalStorageCreate(ThreadLocalStorageCleanupCallback callback);
294 ThreadLocalStorageGet(lldb::thread_key_t key);
297 ThreadLocalStorageSet(lldb::thread_key_t key, void *value);
299 //------------------------------------------------------------------
300 /// Gets the name of a thread in a process.
302 /// This function will name a thread in a process using it's own
303 /// thread name pool, and also will attempt to set a thread name
304 /// using any supported host OS APIs.
307 /// The process ID in which we are trying to get the name of
311 /// The thread ID for which we are trying retrieve the name of.
314 /// A std::string containing the thread name.
315 //------------------------------------------------------------------
317 GetThreadName (lldb::pid_t pid, lldb::tid_t tid);
319 //------------------------------------------------------------------
320 /// Sets the name of a thread in the current process.
323 /// The process ID in which we are trying to name a thread.
326 /// The thread ID which we are trying to name.
329 /// The current thread's name in the current process to \a name.
332 /// \b true if the thread name was able to be set, \b false
334 //------------------------------------------------------------------
336 SetThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name);
338 //------------------------------------------------------------------
339 /// Sets a shortened name of a thread in the current process.
342 /// The process ID in which we are trying to name a thread.
345 /// The thread ID which we are trying to name.
348 /// The current thread's name in the current process to \a name.
351 /// The maximum length for the thread's shortened name.
354 /// \b true if the thread name was able to be set, \b false
357 SetShortThreadName (lldb::pid_t pid, lldb::tid_t tid, const char *name, size_t len);
359 //------------------------------------------------------------------
360 /// Gets the FileSpec of the current process (the process that
361 /// that is running the LLDB code).
364 /// \b A file spec with the program name.
365 //------------------------------------------------------------------
367 GetProgramFileSpec ();
369 //------------------------------------------------------------------
370 /// Given an address in the current process (the process that
371 /// is running the LLDB code), return the name of the module that
372 /// it comes from. This can be useful when you need to know the
373 /// path to the shared library that your code is running in for
374 /// loading resources that are relative to your binary.
376 /// @param[in] host_addr
377 /// The pointer to some code in the current process.
380 /// \b A file spec with the module that contains \a host_addr,
381 /// which may be invalid if \a host_addr doesn't fall into
382 /// any valid module address range.
383 //------------------------------------------------------------------
385 GetModuleFileSpecForHostAddress (const void *host_addr);
389 //------------------------------------------------------------------
390 /// If you have an executable that is in a bundle and want to get
391 /// back to the bundle directory from the path itself, this
392 /// function will change a path to a file within a bundle to the
393 /// bundle directory itself.
396 /// A file spec that might point to a file in a bundle.
398 /// @param[out] bundle_directory
399 /// An object will be filled in with the bundle directory for
400 /// the bundle when \b true is returned. Otherwise \a file is
401 /// left untouched and \b false is returned.
404 /// \b true if \a file was resolved in \a bundle_directory,
405 /// \b false otherwise.
406 //------------------------------------------------------------------
408 GetBundleDirectory (const FileSpec &file, FileSpec &bundle_directory);
410 //------------------------------------------------------------------
411 /// When executable files may live within a directory, where the
412 /// directory represents an executable bundle (like the MacOSX
413 /// app bundles), the locate the executable within the containing
416 /// @param[in,out] file
417 /// A file spec that currently points to the bundle that will
418 /// be filled in with the executable path within the bundle
419 /// if \b true is returned. Otherwise \a file is left untouched.
422 /// \b true if \a file was resolved, \b false if this function
423 /// was not able to resolve the path.
424 //------------------------------------------------------------------
426 ResolveExecutableInBundle (FileSpec &file);
428 //------------------------------------------------------------------
429 /// Find a resource files that are related to LLDB.
431 /// Operating systems have different ways of storing shared
432 /// libraries and related resources. This function abstracts the
433 /// access to these paths.
435 /// @param[in] path_type
436 /// The type of LLDB resource path you are looking for. If the
437 /// enumeration ends with "Dir", then only the \a file_spec's
438 /// directory member gets filled in.
440 /// @param[in] file_spec
441 /// A file spec that gets filled in with the appriopriate path.
444 /// \b true if \a resource_path was resolved, \a false otherwise.
445 //------------------------------------------------------------------
447 GetLLDBPath (PathType path_type,
448 FileSpec &file_spec);
450 //------------------------------------------------------------------
451 /// Set a string that can be displayed if host application crashes.
453 /// Some operating systems have the ability to print a description
454 /// for shared libraries when a program crashes. If the host OS
455 /// supports such a mechanism, it should be implemented to help
456 /// with crash triage.
458 /// @param[in] format
459 /// A printf format that will be used to form a new crash
460 /// description string.
461 //------------------------------------------------------------------
463 SetCrashDescriptionWithFormat (const char *format, ...) __attribute__ ((format (printf, 1, 2)));
466 SetCrashDescription (const char *description);
469 FindProcesses (const ProcessInstanceInfoMatch &match_info,
470 ProcessInstanceInfoList &proc_infos);
472 typedef std::map<lldb::pid_t, bool> TidMap;
473 typedef std::pair<lldb::pid_t, bool> TidPair;
475 FindProcessThreads (const lldb::pid_t pid, TidMap &tids_to_attach);
478 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &proc_info);
480 #if defined (__APPLE__) || defined (__linux__) || defined (__FreeBSD__) || defined (__GLIBC__)
482 GetPosixspawnFlags (ProcessLaunchInfo &launch_info);
485 LaunchProcessPosixSpawn (const char *exe_path, ProcessLaunchInfo &launch_info, ::pid_t &pid);
489 LaunchApplication (const FileSpec &app_file_spec);
492 LaunchProcess (ProcessLaunchInfo &launch_info);
495 RunShellCommand (const char *command, // Shouldn't be NULL
496 const char *working_dir, // Pass NULL to use the current working directory
497 int *status_ptr, // Pass NULL if you don't want the process exit status
498 int *signo_ptr, // Pass NULL if you don't want the signal that caused the process to exit
499 std::string *command_output, // Pass NULL if you don't want the command output
500 uint32_t timeout_sec,
501 const char *shell = LLDB_DEFAULT_SHELL);
503 static lldb::DataBufferSP
504 GetAuxvData (lldb_private::Process *process);
506 static lldb::TargetSP
507 GetDummyTarget (Debugger &debugger);
510 OpenFileInExternalEditor (const FileSpec &file_spec,
514 Backtrace (Stream &strm, uint32_t max_frames);
517 GetEnvironment (StringList &env);
519 enum DynamicLibraryOpenOptions
521 eDynamicLibraryOpenOptionLazy = (1u << 0), // Lazily resolve symbols in this dynamic library
522 eDynamicLibraryOpenOptionLocal = (1u << 1), // Only open a shared library with local access (hide it from the global symbol namespace)
523 eDynamicLibraryOpenOptionLimitGetSymbol = (1u << 2) // DynamicLibraryGetSymbol calls on this handle will only return matches from this shared library
526 DynamicLibraryOpen (const FileSpec &file_spec,
531 DynamicLibraryClose (void *dynamic_library_handle);
534 DynamicLibraryGetSymbol (void *dynamic_library_handle,
535 const char *symbol_name,
539 MakeDirectory (const char* path, uint32_t mode);
542 GetFilePermissions (const char* path, uint32_t &file_permissions);
545 SetFilePermissions (const char* path, uint32_t file_permissions);
548 Symlink (const char *src, const char *dst);
551 Readlink (const char *path, char *buf, size_t buf_len);
554 Unlink (const char *path);
556 static lldb::user_id_t
557 OpenFile (const FileSpec& file_spec,
563 CloseFile (lldb::user_id_t fd,
567 WriteFile (lldb::user_id_t fd,
574 ReadFile (lldb::user_id_t fd,
580 static lldb::user_id_t
581 GetFileSize (const FileSpec& file_spec);
584 GetFileExists (const FileSpec& file_spec);
587 CalculateMD5 (const FileSpec& file_spec,
593 } // namespace lldb_private
595 #endif // #if defined(__cplusplus)
596 #endif // liblldb_Host_h_