1 /* 2 * Copyright (C) 2005-2017 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 17 #ifndef _LIBS_LOGCAT_H /* header boilerplate */ 18 #define _LIBS_LOGCAT_H 19 20 #include <stdio.h> 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #ifndef __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE 27 #ifndef __ANDROID_API__ 28 #define __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE 1 29 #elif __ANDROID_API__ > 24 /* > Nougat */ 30 #define __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE 1 31 #else 32 #define __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE 0 33 #endif 34 #endif 35 36 #if __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE 37 38 /* For managing an in-process logcat function, rather than forking/execing 39 * 40 * It also serves as the basis for the logcat command. 41 * 42 * The following C API allows a logcat instance to be created, run 43 * to completion, and then release all the associated resources. 44 */ 45 46 /* 47 * The opaque context 48 */ 49 #ifndef __android_logcat_context_defined /* typedef boilerplate */ 50 #define __android_logcat_context_defined 51 typedef struct android_logcat_context_internal* android_logcat_context; 52 #endif 53 54 /* Creates a context associated with this logcat instance 55 * 56 * Returns a pointer to the context, or a NULL on error. 57 */ 58 android_logcat_context create_android_logcat(); 59 60 /* Collects and outputs the logcat data to output and error file descriptors 61 * 62 * Will block, performed in-thread and in-process 63 * 64 * The output file descriptor variable, if greater than or equal to 0, is 65 * where the output (ie: stdout) will be sent. The file descriptor is closed 66 * on android_logcat_destroy which terminates the instance, or when an -f flag 67 * (output redirect to a file) is present in the command. The error file 68 * descriptor variable, if greater than or equal to 0, is where the error 69 * stream (ie: stderr) will be sent, also closed on android_logcat_destroy. 70 * The error file descriptor can be set to equal to the output file descriptor, 71 * which will mix output and error stream content, and will defer closure of 72 * the file descriptor on -f flag redirection. Negative values for the file 73 * descriptors will use stdout and stderr FILE references respectively 74 * internally, and will not close the references as noted above. 75 * 76 * Return value is 0 for success, non-zero for errors. 77 */ 78 int android_logcat_run_command(android_logcat_context ctx, int output, int error, 79 int argc, char* const* argv, char* const* envp); 80 81 /* Will not block, performed in-process 82 * 83 * Starts a thread, opens a pipe, returns reading end fd, saves off argv. 84 * The command supports 2>&1 (mix content) and 2>/dev/null (drop content) for 85 * scripted error (stderr) redirection. 86 */ 87 int android_logcat_run_command_thread(android_logcat_context ctx, int argc, 88 char* const* argv, char* const* envp); 89 int android_logcat_run_command_thread_running(android_logcat_context ctx); 90 91 /* Finished with context 92 * 93 * Kill the command thread ASAP (if any), and free up all associated resources. 94 * 95 * Return value is the result of the android_logcat_run_command, or 96 * non-zero for any errors. 97 */ 98 int android_logcat_destroy(android_logcat_context* ctx); 99 100 /* derived helpers */ 101 102 /* 103 * In-process thread that acts like somewhat like libc-like system and popen 104 * respectively. Can not handle shell scripting, only pure calls to the 105 * logcat operations. The android_logcat_system is a wrapper for the 106 * create_android_logcat, android_logcat_run_command and android_logcat_destroy 107 * API above. The android_logcat_popen is a wrapper for the 108 * android_logcat_run_command_thread API above. The android_logcat_pclose is 109 * a wrapper for a reasonable wait until output has subsided for command 110 * completion, fclose on the FILE pointer and the android_logcat_destroy API. 111 */ 112 int android_logcat_system(const char* command); 113 FILE* android_logcat_popen(android_logcat_context* ctx, const char* command); 114 int android_logcat_pclose(android_logcat_context* ctx, FILE* output); 115 116 #endif /* __ANDROID_USE_LIBLOG_LOGCAT_INTERFACE */ 117 118 #ifdef __cplusplus 119 } 120 #endif 121 122 #endif /* _LIBS_LOGCAT_H */ 123