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
23extern "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
51typedef 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 */
58android_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 */
78int 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 */
87int android_logcat_run_command_thread(android_logcat_context ctx, int argc,
88                                      char* const* argv, char* const* envp);
89int 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 */
98int 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 */
112int android_logcat_system(const char* command);
113FILE* android_logcat_popen(android_logcat_context* ctx, const char* command);
114int 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