xref: /openbmc/linux/tools/perf/builtin-help.c (revision 0edbfea5)
1 /*
2  * builtin-help.c
3  *
4  * Builtin help command
5  */
6 #include "perf.h"
7 #include "util/cache.h"
8 #include "builtin.h"
9 #include <subcmd/exec-cmd.h>
10 #include "common-cmds.h"
11 #include <subcmd/parse-options.h>
12 #include <subcmd/run-command.h>
13 #include <subcmd/help.h>
14 #include "util/debug.h"
15 
16 static struct man_viewer_list {
17 	struct man_viewer_list *next;
18 	char name[FLEX_ARRAY];
19 } *man_viewer_list;
20 
21 static struct man_viewer_info_list {
22 	struct man_viewer_info_list *next;
23 	const char *info;
24 	char name[FLEX_ARRAY];
25 } *man_viewer_info_list;
26 
27 enum help_format {
28 	HELP_FORMAT_NONE,
29 	HELP_FORMAT_MAN,
30 	HELP_FORMAT_INFO,
31 	HELP_FORMAT_WEB,
32 };
33 
34 static enum help_format parse_help_format(const char *format)
35 {
36 	if (!strcmp(format, "man"))
37 		return HELP_FORMAT_MAN;
38 	if (!strcmp(format, "info"))
39 		return HELP_FORMAT_INFO;
40 	if (!strcmp(format, "web") || !strcmp(format, "html"))
41 		return HELP_FORMAT_WEB;
42 
43 	pr_err("unrecognized help format '%s'", format);
44 	return HELP_FORMAT_NONE;
45 }
46 
47 static const char *get_man_viewer_info(const char *name)
48 {
49 	struct man_viewer_info_list *viewer;
50 
51 	for (viewer = man_viewer_info_list; viewer; viewer = viewer->next) {
52 		if (!strcasecmp(name, viewer->name))
53 			return viewer->info;
54 	}
55 	return NULL;
56 }
57 
58 static int check_emacsclient_version(void)
59 {
60 	struct strbuf buffer = STRBUF_INIT;
61 	struct child_process ec_process;
62 	const char *argv_ec[] = { "emacsclient", "--version", NULL };
63 	int version;
64 	int ret = -1;
65 
66 	/* emacsclient prints its version number on stderr */
67 	memset(&ec_process, 0, sizeof(ec_process));
68 	ec_process.argv = argv_ec;
69 	ec_process.err = -1;
70 	ec_process.stdout_to_stderr = 1;
71 	if (start_command(&ec_process)) {
72 		fprintf(stderr, "Failed to start emacsclient.\n");
73 		return -1;
74 	}
75 	if (strbuf_read(&buffer, ec_process.err, 20) < 0) {
76 		fprintf(stderr, "Failed to read emacsclient version\n");
77 		goto out;
78 	}
79 	close(ec_process.err);
80 
81 	/*
82 	 * Don't bother checking return value, because "emacsclient --version"
83 	 * seems to always exits with code 1.
84 	 */
85 	finish_command(&ec_process);
86 
87 	if (prefixcmp(buffer.buf, "emacsclient")) {
88 		fprintf(stderr, "Failed to parse emacsclient version.\n");
89 		goto out;
90 	}
91 
92 	version = atoi(buffer.buf + strlen("emacsclient"));
93 
94 	if (version < 22) {
95 		fprintf(stderr,
96 			"emacsclient version '%d' too old (< 22).\n",
97 			version);
98 	} else
99 		ret = 0;
100 out:
101 	strbuf_release(&buffer);
102 	return ret;
103 }
104 
105 static void exec_woman_emacs(const char *path, const char *page)
106 {
107 	char sbuf[STRERR_BUFSIZE];
108 
109 	if (!check_emacsclient_version()) {
110 		/* This works only with emacsclient version >= 22. */
111 		char *man_page;
112 
113 		if (!path)
114 			path = "emacsclient";
115 		if (asprintf(&man_page, "(woman \"%s\")", page) > 0) {
116 			execlp(path, "emacsclient", "-e", man_page, NULL);
117 			free(man_page);
118 		}
119 		warning("failed to exec '%s': %s", path,
120 			strerror_r(errno, sbuf, sizeof(sbuf)));
121 	}
122 }
123 
124 static void exec_man_konqueror(const char *path, const char *page)
125 {
126 	const char *display = getenv("DISPLAY");
127 
128 	if (display && *display) {
129 		char *man_page;
130 		const char *filename = "kfmclient";
131 		char sbuf[STRERR_BUFSIZE];
132 
133 		/* It's simpler to launch konqueror using kfmclient. */
134 		if (path) {
135 			const char *file = strrchr(path, '/');
136 			if (file && !strcmp(file + 1, "konqueror")) {
137 				char *new = strdup(path);
138 				char *dest = strrchr(new, '/');
139 
140 				/* strlen("konqueror") == strlen("kfmclient") */
141 				strcpy(dest + 1, "kfmclient");
142 				path = new;
143 			}
144 			if (file)
145 				filename = file;
146 		} else
147 			path = "kfmclient";
148 		if (asprintf(&man_page, "man:%s(1)", page) > 0) {
149 			execlp(path, filename, "newTab", man_page, NULL);
150 			free(man_page);
151 		}
152 		warning("failed to exec '%s': %s", path,
153 			strerror_r(errno, sbuf, sizeof(sbuf)));
154 	}
155 }
156 
157 static void exec_man_man(const char *path, const char *page)
158 {
159 	char sbuf[STRERR_BUFSIZE];
160 
161 	if (!path)
162 		path = "man";
163 	execlp(path, "man", page, NULL);
164 	warning("failed to exec '%s': %s", path,
165 		strerror_r(errno, sbuf, sizeof(sbuf)));
166 }
167 
168 static void exec_man_cmd(const char *cmd, const char *page)
169 {
170 	char sbuf[STRERR_BUFSIZE];
171 	char *shell_cmd;
172 
173 	if (asprintf(&shell_cmd, "%s %s", cmd, page) > 0) {
174 		execl("/bin/sh", "sh", "-c", shell_cmd, NULL);
175 		free(shell_cmd);
176 	}
177 	warning("failed to exec '%s': %s", cmd,
178 		strerror_r(errno, sbuf, sizeof(sbuf)));
179 }
180 
181 static void add_man_viewer(const char *name)
182 {
183 	struct man_viewer_list **p = &man_viewer_list;
184 	size_t len = strlen(name);
185 
186 	while (*p)
187 		p = &((*p)->next);
188 	*p = zalloc(sizeof(**p) + len + 1);
189 	strncpy((*p)->name, name, len);
190 }
191 
192 static int supported_man_viewer(const char *name, size_t len)
193 {
194 	return (!strncasecmp("man", name, len) ||
195 		!strncasecmp("woman", name, len) ||
196 		!strncasecmp("konqueror", name, len));
197 }
198 
199 static void do_add_man_viewer_info(const char *name,
200 				   size_t len,
201 				   const char *value)
202 {
203 	struct man_viewer_info_list *new = zalloc(sizeof(*new) + len + 1);
204 
205 	strncpy(new->name, name, len);
206 	new->info = strdup(value);
207 	new->next = man_viewer_info_list;
208 	man_viewer_info_list = new;
209 }
210 
211 static int add_man_viewer_path(const char *name,
212 			       size_t len,
213 			       const char *value)
214 {
215 	if (supported_man_viewer(name, len))
216 		do_add_man_viewer_info(name, len, value);
217 	else
218 		warning("'%s': path for unsupported man viewer.\n"
219 			"Please consider using 'man.<tool>.cmd' instead.",
220 			name);
221 
222 	return 0;
223 }
224 
225 static int add_man_viewer_cmd(const char *name,
226 			      size_t len,
227 			      const char *value)
228 {
229 	if (supported_man_viewer(name, len))
230 		warning("'%s': cmd for supported man viewer.\n"
231 			"Please consider using 'man.<tool>.path' instead.",
232 			name);
233 	else
234 		do_add_man_viewer_info(name, len, value);
235 
236 	return 0;
237 }
238 
239 static int add_man_viewer_info(const char *var, const char *value)
240 {
241 	const char *name = var + 4;
242 	const char *subkey = strrchr(name, '.');
243 
244 	if (!subkey)
245 		return error("Config with no key for man viewer: %s", name);
246 
247 	if (!strcmp(subkey, ".path")) {
248 		if (!value)
249 			return config_error_nonbool(var);
250 		return add_man_viewer_path(name, subkey - name, value);
251 	}
252 	if (!strcmp(subkey, ".cmd")) {
253 		if (!value)
254 			return config_error_nonbool(var);
255 		return add_man_viewer_cmd(name, subkey - name, value);
256 	}
257 
258 	warning("'%s': unsupported man viewer sub key.", subkey);
259 	return 0;
260 }
261 
262 static int perf_help_config(const char *var, const char *value, void *cb)
263 {
264 	enum help_format *help_formatp = cb;
265 
266 	if (!strcmp(var, "help.format")) {
267 		if (!value)
268 			return config_error_nonbool(var);
269 		*help_formatp = parse_help_format(value);
270 		if (*help_formatp == HELP_FORMAT_NONE)
271 			return -1;
272 		return 0;
273 	}
274 	if (!strcmp(var, "man.viewer")) {
275 		if (!value)
276 			return config_error_nonbool(var);
277 		add_man_viewer(value);
278 		return 0;
279 	}
280 	if (!prefixcmp(var, "man."))
281 		return add_man_viewer_info(var, value);
282 
283 	return 0;
284 }
285 
286 static struct cmdnames main_cmds, other_cmds;
287 
288 void list_common_cmds_help(void)
289 {
290 	unsigned int i, longest = 0;
291 
292 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
293 		if (longest < strlen(common_cmds[i].name))
294 			longest = strlen(common_cmds[i].name);
295 	}
296 
297 	puts(" The most commonly used perf commands are:");
298 	for (i = 0; i < ARRAY_SIZE(common_cmds); i++) {
299 		printf("   %-*s   ", longest, common_cmds[i].name);
300 		puts(common_cmds[i].help);
301 	}
302 }
303 
304 static int is_perf_command(const char *s)
305 {
306 	return is_in_cmdlist(&main_cmds, s) ||
307 		is_in_cmdlist(&other_cmds, s);
308 }
309 
310 static const char *cmd_to_page(const char *perf_cmd)
311 {
312 	char *s;
313 
314 	if (!perf_cmd)
315 		return "perf";
316 	else if (!prefixcmp(perf_cmd, "perf"))
317 		return perf_cmd;
318 
319 	return asprintf(&s, "perf-%s", perf_cmd) < 0 ? NULL : s;
320 }
321 
322 static void setup_man_path(void)
323 {
324 	char *new_path;
325 	const char *old_path = getenv("MANPATH");
326 
327 	/* We should always put ':' after our path. If there is no
328 	 * old_path, the ':' at the end will let 'man' to try
329 	 * system-wide paths after ours to find the manual page. If
330 	 * there is old_path, we need ':' as delimiter. */
331 	if (asprintf(&new_path, "%s:%s", system_path(PERF_MAN_PATH), old_path ?: "") > 0) {
332 		setenv("MANPATH", new_path, 1);
333 		free(new_path);
334 	} else {
335 		error("Unable to setup man path");
336 	}
337 }
338 
339 static void exec_viewer(const char *name, const char *page)
340 {
341 	const char *info = get_man_viewer_info(name);
342 
343 	if (!strcasecmp(name, "man"))
344 		exec_man_man(info, page);
345 	else if (!strcasecmp(name, "woman"))
346 		exec_woman_emacs(info, page);
347 	else if (!strcasecmp(name, "konqueror"))
348 		exec_man_konqueror(info, page);
349 	else if (info)
350 		exec_man_cmd(info, page);
351 	else
352 		warning("'%s': unknown man viewer.", name);
353 }
354 
355 static int show_man_page(const char *perf_cmd)
356 {
357 	struct man_viewer_list *viewer;
358 	const char *page = cmd_to_page(perf_cmd);
359 	const char *fallback = getenv("PERF_MAN_VIEWER");
360 
361 	setup_man_path();
362 	for (viewer = man_viewer_list; viewer; viewer = viewer->next)
363 		exec_viewer(viewer->name, page); /* will return when unable */
364 
365 	if (fallback)
366 		exec_viewer(fallback, page);
367 	exec_viewer("man", page);
368 
369 	pr_err("no man viewer handled the request");
370 	return -1;
371 }
372 
373 static int show_info_page(const char *perf_cmd)
374 {
375 	const char *page = cmd_to_page(perf_cmd);
376 	setenv("INFOPATH", system_path(PERF_INFO_PATH), 1);
377 	execlp("info", "info", "perfman", page, NULL);
378 	return -1;
379 }
380 
381 static int get_html_page_path(char **page_path, const char *page)
382 {
383 	struct stat st;
384 	const char *html_path = system_path(PERF_HTML_PATH);
385 
386 	/* Check that we have a perf documentation directory. */
387 	if (stat(mkpath("%s/perf.html", html_path), &st)
388 	    || !S_ISREG(st.st_mode)) {
389 		pr_err("'%s': not a documentation directory.", html_path);
390 		return -1;
391 	}
392 
393 	return asprintf(page_path, "%s/%s.html", html_path, page);
394 }
395 
396 /*
397  * If open_html is not defined in a platform-specific way (see for
398  * example compat/mingw.h), we use the script web--browse to display
399  * HTML.
400  */
401 #ifndef open_html
402 static void open_html(const char *path)
403 {
404 	execl_cmd("web--browse", "-c", "help.browser", path, NULL);
405 }
406 #endif
407 
408 static int show_html_page(const char *perf_cmd)
409 {
410 	const char *page = cmd_to_page(perf_cmd);
411 	char *page_path; /* it leaks but we exec bellow */
412 
413 	if (get_html_page_path(&page_path, page) < 0)
414 		return -1;
415 
416 	open_html(page_path);
417 
418 	return 0;
419 }
420 
421 int cmd_help(int argc, const char **argv, const char *prefix __maybe_unused)
422 {
423 	bool show_all = false;
424 	enum help_format help_format = HELP_FORMAT_MAN;
425 	struct option builtin_help_options[] = {
426 	OPT_BOOLEAN('a', "all", &show_all, "print all available commands"),
427 	OPT_SET_UINT('m', "man", &help_format, "show man page", HELP_FORMAT_MAN),
428 	OPT_SET_UINT('w', "web", &help_format, "show manual in web browser",
429 			HELP_FORMAT_WEB),
430 	OPT_SET_UINT('i', "info", &help_format, "show info page",
431 			HELP_FORMAT_INFO),
432 	OPT_END(),
433 	};
434 	const char * const builtin_help_subcommands[] = {
435 		"buildid-cache", "buildid-list", "diff", "evlist", "help", "list",
436 		"record", "report", "bench", "stat", "timechart", "top", "annotate",
437 		"script", "sched", "kmem", "lock", "kvm", "test", "inject", "mem", "data",
438 #ifdef HAVE_LIBELF_SUPPORT
439 		"probe",
440 #endif
441 #ifdef HAVE_LIBAUDIT_SUPPORT
442 		"trace",
443 #endif
444 	NULL };
445 	const char *builtin_help_usage[] = {
446 		"perf help [--all] [--man|--web|--info] [command]",
447 		NULL
448 	};
449 	const char *alias;
450 	int rc = 0;
451 
452 	load_command_list("perf-", &main_cmds, &other_cmds);
453 
454 	perf_config(perf_help_config, &help_format);
455 
456 	argc = parse_options_subcommand(argc, argv, builtin_help_options,
457 			builtin_help_subcommands, builtin_help_usage, 0);
458 
459 	if (show_all) {
460 		printf("\n Usage: %s\n\n", perf_usage_string);
461 		list_commands("perf commands", &main_cmds, &other_cmds);
462 		printf(" %s\n\n", perf_more_info_string);
463 		return 0;
464 	}
465 
466 	if (!argv[0]) {
467 		printf("\n usage: %s\n\n", perf_usage_string);
468 		list_common_cmds_help();
469 		printf("\n %s\n\n", perf_more_info_string);
470 		return 0;
471 	}
472 
473 	alias = alias_lookup(argv[0]);
474 	if (alias && !is_perf_command(argv[0])) {
475 		printf("`perf %s' is aliased to `%s'\n", argv[0], alias);
476 		return 0;
477 	}
478 
479 	switch (help_format) {
480 	case HELP_FORMAT_MAN:
481 		rc = show_man_page(argv[0]);
482 		break;
483 	case HELP_FORMAT_INFO:
484 		rc = show_info_page(argv[0]);
485 		break;
486 	case HELP_FORMAT_WEB:
487 		rc = show_html_page(argv[0]);
488 		break;
489 	case HELP_FORMAT_NONE:
490 		/* fall-through */
491 	default:
492 		rc = -1;
493 		break;
494 	}
495 
496 	return rc;
497 }
498