Chapter 7
The memadvise Command
This chapter describes the memadvise command and its options.
How the memadvise Command Works
To use the memadvise command, you place the word "memadvise" in front of the command that you normally use to link your program. For example:
- memadvise cc -g -o my_program foo.c my_prog.o utils.o -lxyz
Your normal link command becomes the input to the memadvise command. The memadvise command does the following with your link command:
Memory Advisor usually gets control to process these files by telling the compiler to invoke the memadvise command as the loader (instead of the system loader). Each Memory Advisor installation includes a compiler configuration file that tells each tested compiler how to invoke the memadvise command as the loader. If you are using a compiler that has no entry in the compiler configuration file, you must add an entry. See Compiler Configuration File Organization for details.
In processing these files, the memadvise command checks whether the files have changed since they were last processed (if ever). If they have not changed, the memadvise command uses the already-processed version instead of reprocessing the file. Memory Advisor stores processed files in a temporary directory. (See The -T Option for detailed information on temporary directories.)
In processing your files, the memadvise command also instruments these files with error-checking code. It is this error-checking code that produces the error messages at run-time.
Note: We designed Memory Advisor for building processed executable programs. Do not use the memadvise command in building shared libraries. Only use the memadvise command to build main programs that you are linking with your shared libraries. If you use the memadvise command in building a shared library, you will insert error-checking code into the library. Then when you use the memadvise command to build an application that uses this shared library, you will insert error-checking code into the error-checking code that is already in the shared library.
Memory Advisor Operating Modes
Memory Advisor provides several operating modes. These determine how Memory Advisor links your program and what Memory Advisor functionality is present in the resulting program. The following operating modes are available:
- OMT mode. When you build your program in this mode, all Memory Advisor debugging capabilities (described in How Memory Advisor Works) are available in your linked program.
- LITE mode. When you build your program in this mode, Memory Advisor uses a simpler technology in the resulting executable (described in How Memory Advisor Works). Building in this mode takes less time, and the resulting executable runs more quickly, but with a reduced level of error detection.
- Debug-only mode. When you build your program in this mode, only Memory Advisor's discretionary debugging capabilities, as described in Chapter 17, Discretionary Debugging, are available in your linked executable. Use this mode when you want your program to generate debug output using the Memory Advisor API, without the overhead of Memory Advisor's full memory-access checks.
- Stubs mode. When you build your program in this mode, you disable all of Memory Advisor's capabilities. This mode is useful when your program has calls to Memory Advisor's API functions and you want to rebuild the program without compiling out these calls.
You determine the operating mode for a processed program when you link your program, based on the value of the -mode command-line option (described below), or the mode command configuration option (described in The mode Option).
Syntax of the memadvise Command
The syntax for the memadvise command is:
- memadvise [memadvise_options] linker linker-options
where:
You can set most of Memory Advisor's command-line options in one of your compiler configuration files. You do not need specify them on the memadvise command line. Note, however, that options you specify via the command line take precedence over options from a compiler configuration file. See Command Configuration Options for more information.
Command-Line Options
The following sections describe the memadvise_options.
The -custid Option
The -custid (customer ID) option prints your customer ID. This option works only if you have installed your Memory Advisor permanent license(s), because your customer ID is in your permanent license data file. You should always include your customer ID when reporting a problem to or asking a question of PLATINUM Technical Support. This option is mutually exclusive with all other options.
The -D Option
The -D (do not lock files) option prevents Memory Advisor from locking its temporary files while processing them. Ordinarily, the memadvise command gets a lock on a temporary file before processing it, so two users cannot accidentally process the same file at the same time. If your lock daemon does not work correctly, you may have difficulty getting locks. In this case, you may want to use this option. This option corresponds to the dont_lock_files command configuration option.
Note: Use this option with caution. If you use the -D option and another user uses the same temporary file directory, data corruption could result.
The -db Option
The -db boundary_size (data boundary size) option specifies the size of the boundary that Memory Advisor allocates on either side of a global data area. The default boundary size is 8 bytes. If you specify a different value, it must be a multiple of 8. You may disable global-data-checking by setting the boundary size to 0 (zero). This is the same as specifying the -nd option. The -db and -nd options are mutually exclusive. This option corresponds to the data_boundary_size command configuration option.
Note: This option is for use in OMT mode only.
The -du Option
The -du (data boundary unsafe) option always inserts boundaries around global data, even though it may not always be safe to do so. This option is only for advanced Memory Advisor users. See Chapter 16, Stack and Global Data Error Detection, for more details. This option and the -nd or -db 0 options are mutually exclusive. This option corresponds to the data_boundary_unsafe command configuration option.
Note: This option is for use in OMT mode only.
The -f Option
The -f (force) option forces the reprocessing of all libraries and object files involved in the link command that you specify. Normally, Memory Advisor processes only those files that have changed since the last time you modified them. You may need to force reprocessing in certain rare cases; for example, if your machine crashes while Memory Advisor is running.
The -F Option
The -F (full paths) option specifies whether to generate the loader command line with full paths to each library. By default, the memadvise command generates loader command lines using -L<path> -l<library_name> syntax, because these command lines are generally shorter. This avoids long loader commands on systems with restricted command lengths. If you use the -nx option, you should use this option. This option corresponds to the full_paths command configuration option.
The -lic Option
The -lic (license information) option generates a unique license token for the machine on which you run the memadvise command. This license token is necessary for generating your Memory Advisor permanent licenses. This option is mutually exclusive with all other command-line options.
The -M Option
The -M (must use temporary directory) option places all processed files in the temporary directory. If you use this option, you should also use the -T option to specify the temporary directory. This option corresponds to the must_use_temp_lib command configuration option.
The -mode Option
The -mode mode (operating mode) option specifies the mode in which to build the processed executable. See Memory Advisor Operating Modes for a description of the different Memory Advisor operating modes. Valid values for mode are omt, lite, debug, and stubs. This option corresponds to the mode command configuration option.
The -N Option
The -N path (no temporary directories) option specifies a colon-separated list of directories in which you do not want Memory Advisor to create temporary directories, for example, /lib:/usr/lib. If you specify this option, you should also use the -T option to specify where you do want Memory Advisor to place its files. This option corresponds to the no_temp_dirs command configuration option.
The -nd Option
The -nd (no data boundaries) option prevents global data checking. This option is the same as and mutually exclusive with specifying -db 0. This option corresponds to the data_boundary_size command configuration option.
Note: This option is for use in OMT mode only.
The -NW Option
The -NW (no wait) option causes Memory Advisor to exit with a warning if no license token is available when you invoke the memadvise command. This is the default behavior. This option corresponds to the lic_wait_mode command configuration option.
The -nx Option
The -nx (no file extension) option prevents Memory Advisor from adding file extensions (see the -x command-line option) to the names of processed files. You may need this option for systems with 14-character file name restrictions. If you use this option, you should also use the -F command-line option. We have set the file extension to the most appropriate value for your environment. You should not use this option except by advice of PLATINUM Technical Support. This option corresponds to the file_ext command configuration option.
The -q Option
The -q (quiet) option prevents any informational messages from displaying. You will still see warning and error messages. This option corresponds to the quiet command configuration option.
The -s Option
The -s (standalone) option lets you process one or more files without actually linking a program. This may be useful, for example, if you need to process a library that is not on your normal link line, such as one that your program dynamically links via the dlopen() call.
The -T Option
The -T dir (temporary directory) option specifies the directory in which you want Memory Advisor to create its directory for holding temporary files. By default, this location is $MA_HOME/tmplib. This option corresponds to the temp_lib command configuration option.
As part of its normal execution, Memory Advisor processes every library archive and object file in your memadvise command. This creates directories and files at various points in the file system. When Memory Advisor processes object files and library archives, it creates temporary copies of those object files and library archives. The location that Memory Advisor chooses for its temporary files is in the directory that the -T command-line option or temp_lib command configuration option specifies:
If none of these are true, Memory Advisor chooses the .ma.tmp directory in the directory where the object file or library archive resides.
When Memory Advisor looks for the processed version of a library, it checks the directories in the same order mentioned above. If it cannot find the library, or if the library is out of date, it creates another processed copy of the library and puts it in the temporary library directory.
The -trace Option
The -trace symbol_name (trace symbol) option causes Memory Advisor to report whenever it encounters or references the named symbol during processing. Specifying this option causes Memory Advisor to behave as if you had also specified the -f option. Memory Advisor will reprocess all files on the link line so that it can produce the trace information. This option can be useful in understanding the cause of undefined or multiply-defined symbols.
The -vN Option
The -vN (verbosity level) option sets the verbosity level to the specified value (N). This option corresponds to the verbose command configuration option. Valid values for N are:
- 0
- No output from the memadvise command unless an error occurs.
- 1
- Provides a running status of the memadvise command as it runs. This includes the name of each file as Memory Advisor processes it, and the start and end of a link step if Memory Advisor is performing linking. This is equivalent to specifying the -v command-line option with no argument.
- 2
- Provides verbose debug output. This shows each action the memadvise command is taking, including the values of all options and the full command line for each command invoked. PLATINUM Technical Support will often request this type of output when attempting to diagnose a problem.
- 5
- Provides very verbose output. This is equivalent to the -V command-line option.
The -v Option
The -v (verbose) option gives verbose output about what the memadvise command is doing. This provides a running status of the command's progress. This option is equivalent to -v1.
The -V Option
The -V (very verbose) option gives extremely verbose output about what the memadvise command is doing. Because of the voluminous size of the output, you should not use this option except when PLATINUM Technical Support asks for this information to help determine the cause of a problem. This option is equivalent to -v5.
The -version Option
The -version (version) option prints detailed version information about the Memory Advisor product that you are using. You should always include this output in any problem report that you send to PLATINUM Technical Support. This option is mutually exclusive with all other options.
The -W Option
The -W (wait for license) option causes Memory Advisor to wait for a license to become available, if none are available when you invoke the memadvise command. This option corresponds to the lic_wait_mode command configuration option.
The -x Option
The -x extension (file extension) option specifies the file extension Memory Advisor adds to processed files so that the system loader cannot confuse the processed files with unprocessed ones. For example, if the extension is ext when Memory Advisor processes libc.so, it will write the processed file to the libc_ext.so temporary file. The system loader cannot confuse -lc with -lc_ext. This option corresponds to the file_ext command configuration option.
We have set the file extension to the most appropriate value for your environment. You should not change the extension except by advice of PLATINUM Technical Support.
Examples of Using the memadvise Command
This section gives examples of performing some common tasks using the memadvise command.
Determining Your Customer ID
Use the following command to determine your customer ID:
- memadvise -custid
If you have installed your Memory Advisor permanent license file, this command prints your customer ID. Please include your customer ID in any correspondence with PLATINUM Technical Support.
Generating License Information for Your Permanent Licenses
Use the following command to generate license information for your permanent license:
- memadvise -lic
Run this command on each machine that will serve your Memory Advisor licenses. See Chapter 12, License Installation, for more details.
Determining Your Memory Advisor Version
Use the following command to determine your Memory Advisor version:
- memadvise -version
This command prints version information about the copy of Memory Advisor that you have installed. It identifies the version of Memory Advisor, the kind of hardware you are running, and the operating system version you are running. This information is often invaluable in resolving problems. Please include this information in any correspondence with PLATINUM Technical Support.
Reprocessing a Single File
Use the following command to reprocess a single file:
- memadvise [-f] -s file
For example:
- memadvise -f -s /home/thisproj/lib/libproj.so
This example command reprocesses the libproj shared library without linking any main program. There is rarely any need to process a single file by itself. However, this option can be useful in debugging problems in processing a single file.
Linking With the Memory Advisor Debugging Library
Use the following command to link with the Memory Advisor debugging library:
- memadvise -mode debug linker linker_options
For example:
- memadvise -mode debug cc -g -o myprog myprog.o -lmylib
This command links the myprog application with the Memory Advisor debugging library. This library does not provide error-checking. It provides debugging support for your application. This library provides API routines for the Memory Advisor discretionary debugging facilities, including the MADBG() family of macros and the MaStack*() family of stack tracing functions. See Chapter 9, Application Programming Interface, for detailed descriptions of these functions.
Copyright ©1996 PLATINUM technology, inc. All rights reserved.
Last modified 1/29/96
For more information contact info@platinum.com