Print this page
9842 man page typos and spelling
   1 '\" te
   2 .\"  Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CRLE 1 "Oct 6, 2008"
   7 .SH NAME
   8 crle \- configure runtime linking environment
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcrle\fR [\fB-64\fR] [\fB-a\fR \fIname\fR] [\fB-A\fR \fIname\fR] [\fB-c\fR \fIconf\fR] [\fB-e\fR \fIenv\fR] [\fB-E\fR \fIenv\fR]
  13      [\fB-f\fR \fIflags\fR] [\fB-i\fR \fIname\fR] [\fB-I\fR \fIname\fR] [\fB-g\fR \fIname\fR] [\fB-G\fR \fIname\fR]
  14      [\fB-l\fR \fIdir\fR] [\fB-o\fR \fIdir\fR] [\fB-s\fR \fIdir\fR] [\fB-t\fR [ ELF | AOUT]] [\fB-u\fR] [\fB-v\fR]
  15 .fi
  16 
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 The \fBcrle\fR utility provides for the creation and display of a runtime
  21 linking configuration file. The configuration file is read and interpreted by
  22 the runtime linker, \fBld.so.1\fR(1), during process startup. The runtime
  23 linker attempts to read a default configuration file for all processes. For
  24 32-bit processes, the default configuration file is \fB/var/ld/ld.config\fR.
  25 For 64-bit processes, the default configuration file is
  26 \fB/var/ld/64/ld.config\fR.
  27 .sp
  28 .LP
  29 Without any arguments, or with just the \fB-c\fR option, \fBcrle\fR displays
  30 configuration information. This information includes the contents of a
  31 configuration file, any system defaults and the command-line required to
  32 regenerate the configuration file. When used with any other options, a new
  33 configuration file is created or updated.
  34 .sp
  35 .LP
  36 The runtime linker can also be directed to an alternative configuration file by
  37 setting one of the \fBLD_CONFIG\fR family of environment variable.
  38 \fBLD_CONFIG\fR applies to both 32-bit and 64-bit programs. Since 32-bit and
  39 64-bit configuration files differ, a single configuration file cannot be used
  40 for both class of object. Hence, \fBLD_CONFIG\fR can adversely affect program
  41 execution in cases where a program of one class executes a program of the other
  42 class. In particular, it is common practice for the 32-bit version of standard
  43 Solaris utilities to execute their 64-bit counterpart. \fBLD_CONFIG\fR cannot
  44 be successfully used in this case. Therefore, the use of the \fBLD_CONFIG_32\fR
  45 and \fBLD_CONFIG_64\fR environment variables, that precisely target the
  46 appropriate class of process, is recommended.
  47 .sp
  48 .LP
  49 Creating an incorrect configuration file in the standard location,
  50 \fB/var/ld\fR, can prevent programs from running, and can therefore be
  51 difficult to recover from. To guard against this situation, it is recommented
  52 that new configuration files first be created in a temporary location. Then set
  53 the appropriate \fBLD_CONFIG\fR environment variable to this new configuration
  54 file. This setting causes the new configuration file to be used by the runtime
  55 linker instead of any default. After verification, the new configuration file
  56 can be moved to the default location if desired. At any time, the environment
  57 variable \fBLD_NOCONFIG\fR can be set to any value to instruct the runtime
  58 linker to ignore any configuration files. This setting can prove useful during
  59 experimentation.
  60 .sp
  61 .LP
  62 A configuration file can contain the following information.
  63 .sp
  64 .ne 2
  65 .na
  66 \fBDefault Search Paths\fR
  67 .ad
  68 .sp .6
  69 .RS 4n
  70 The runtime linker uses a prescribed search path for locating the dynamic
  71 dependencies of an object. This search path starts with the components of any


 166 system components. When this situation arises the flexibility offered by
 167 dynamic linking system components can be compromised. This type of application
 168 failure can be very difficult to diagnose. No verification of directory cache
 169 information is performed. Any changes to the directory structure are not seen
 170 by a process until the cache is rebuilt.
 171 .sp
 172 .LP
 173 System shared objects are often well tuned, and can show little benefit from
 174 being cached. The directory cache and alternative object features are typically
 175 applicable to user applications and shared objects, and may only show
 176 improvement in some very specific cases.
 177 .sp
 178 .LP
 179 \fBcrle\fR creates alternate objects for the shared objects that are discovered
 180 when using the \fB-I\fR and \fB-G\fR options, using \fBdldump\fR(3C). The
 181 alternate object is created in the directory specified by the preceding
 182 \fB-o\fR option, or defaults to the directory in which the configuration file
 183 is created. The flags used by \fBdldump()\fR are specified using the \fB-f\fR
 184 option, or default to \fBRTLD_REL_RELATIVE\fR.
 185 .SH OPTIONS
 186 .sp
 187 .LP
 188 The following options are supported.
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB-64\fR\fR
 193 .ad
 194 .sp .6
 195 .RS 4n
 196 Specify to process 64-bit objects, the default is 32-bit. Use \fB-64\fR to
 197 create a 64-bit specific configuration file.
 198 .RE
 199 
 200 .sp
 201 .ne 2
 202 .na
 203 \fB\fB-a\fR \fIname\fR\fR
 204 .ad
 205 .sp .6
 206 .RS 4n


 777 \&.....
 778 $ \fBLD_DEBUG=files LD_PRELOAD=preload.so.2 ./main\fR
 779 \&.....
 780 18764: file=preload.so.2;  preloaded
 781 18764: file=/local/lib/preload.so.2  [ ELF ]; generating link map
 782 \&.....
 783 18764: file=preload.so.1;  preloaded
 784 18764: file=/local/lib/preload.so.1  [ ELF ]; generating link map
 785 \&.....
 786 .fi
 787 .in -2
 788 .sp
 789 
 790 .sp
 791 .LP
 792 With this configuration file, a replaceable search path has been specified
 793 together with a permanent preload object which becomes appended to the process
 794 environment definition.
 795 
 796 .SH EXIT STATUS
 797 .sp
 798 .LP
 799 The creation or display of a configuration file results in a \fB0\fR being
 800 returned. Otherwise, any error condition is accompanied with a diagnostic
 801 message and a non-zero value being returned.
 802 .SH NOTES
 803 .sp
 804 .LP
 805 The ability to tag an alternative application to use an application-specific
 806 configuration file, is possible if the original application contains one of the
 807 \fI\&.dynamic\fR tags \fBDT_FLAGS_1\fR or \fBDT_FEATURE_1\fR. Without these
 808 entries, a configuration file must be specified using the \fBLD_CONFIG\fR
 809 environment variable. Care should be exercised with this latter method as this
 810 environment variable is visible to any forked applications.
 811 .sp
 812 .LP
 813 The use of the \fB-u\fR option requires at least version 2 of \fBcrle\fR. This
 814 version level is evident from displaying the contents of a configuration file.
 815 .sp
 816 .in +2
 817 .nf
 818 $ \fBcrle\fR
 819 
 820 Configuration file [2]: /var/ld/ld.config
 821   ......
 822 .fi
 823 .in -2


 831 option. Although a version 1 configuration file update is possible, the
 832 configuration file contents might be insufficient for \fBcrle\fR to compute the
 833 entire update requirements.
 834 .sp
 835 .LP
 836 Configuration files contain platform specific binary data. A given
 837 configuration file can only be interpreted by software with the same machine
 838 class and byte ordering. However, the information necessary to enforce this
 839 restriction was not included in configuration files until \fBSXCE\fR build
 840 \fB41\fR. As of this \fBSXCE\fR build, configuration files have system
 841 identification information at the beginning of the file. This additional
 842 information is used by \fBcrle\fR and the runtime to check their compatibility
 843 with configuration files. This information also allows the \fBfile\fR(1)
 844 command to properly identify  configuration files. For backward compatibility,
 845 older files that are missing this information are still accepted, although
 846 without the identification and error checking that would otherwise be possible.
 847 When processing an update (\fB-u\fR) operation for an older file that lacks
 848 system information, \fBcrle\fR does not add system identification information
 849 to the result.
 850 .SH FILES
 851 .sp
 852 .ne 2
 853 .na
 854 \fB\fB/var/ld/ld.config\fR\fR
 855 .ad
 856 .sp .6
 857 .RS 4n
 858 Default configuration file for 32-bit applications.
 859 .RE
 860 
 861 .sp
 862 .ne 2
 863 .na
 864 \fB\fB/var/ld/64/ld.config\fR\fR
 865 .ad
 866 .sp .6
 867 .RS 4n
 868 Default configuration file for 64-bit applications.
 869 .RE
 870 
 871 .sp


 902 .ne 2
 903 .na
 904 \fB\fB/usr/lib/libcrle.so.1\fR\fR
 905 .ad
 906 .sp .6
 907 .RS 4n
 908 Audit library that is employed to \fBdldump\fR(3C) 32-bit objects.
 909 .RE
 910 
 911 .sp
 912 .ne 2
 913 .na
 914 \fB\fB/usr/lib/64/libcrle.so.1\fR\fR
 915 .ad
 916 .sp .6
 917 .RS 4n
 918 Audit library that is employed to \fBdldump\fR(3C) 64-bit objects.
 919 .RE
 920 
 921 .SH ENVIRONMENT VARIABLES
 922 .sp
 923 .LP
 924 There are no environment variables that are referenced by \fBcrle\fR. However,
 925 several environment variables affect the runtime linkers behavior in regard to
 926 the processing of configuration files that are created by \fBcrle\fR.
 927 .sp
 928 .ne 2
 929 .na
 930 \fB\fBLD_CONFIG\fR, \fBLD_CONFIG_32\fR and \fBLD_CONFIG_64\fR\fR
 931 .ad
 932 .sp .6
 933 .RS 4n
 934 Provide an alternative configuration file.
 935 .RE
 936 
 937 .sp
 938 .ne 2
 939 .na
 940 \fB\fBLD_NOCONFIG\fR, \fBLD_NOCONFIG_32\fR and \fBLD_NOCONFIG_64\fR\fR
 941 .ad
 942 .sp .6


 958 .ne 2
 959 .na
 960 \fB\fBLD_NOENVCONFIG\fR, \fBLD_NOENVCONFIG_32\fR and \fBLD_NOENVCONFIG_64\fR\fR
 961 .ad
 962 .sp .6
 963 .RS 4n
 964 Disable environment variable processing from a configuration file.
 965 .RE
 966 
 967 .sp
 968 .ne 2
 969 .na
 970 \fB\fBLD_NOOBJALTER\fR, \fBLD_NOOBJALTER_32\fR and \fBLD_NOOBJALTER_64\fR\fR
 971 .ad
 972 .sp .6
 973 .RS 4n
 974 Disable alternative object processing from a configuration file.
 975 .RE
 976 
 977 .SH ATTRIBUTES
 978 .sp
 979 .LP
 980 See \fBattributes\fR(5) for descriptions of the following attributes.
 981 .sp
 982 
 983 .sp
 984 .TS
 985 box;
 986 c | c
 987 l | l .
 988 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 989 _
 990 Interface Stability     Committed
 991 .TE
 992 
 993 .SH SEE ALSO
 994 .sp
 995 .LP
 996 \fBfile\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBdldump\fR(3C),
 997 \fBtempnam\fR(3C), \fBattributes\fR(5)
 998 .sp
 999 .LP
1000 \fILinker and Libraries Guide\fR
   1 '\" te
   2 .\"  Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CRLE 1 "Oct 6, 2008"
   7 .SH NAME
   8 crle \- configure runtime linking environment
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcrle\fR [\fB-64\fR] [\fB-a\fR \fIname\fR] [\fB-A\fR \fIname\fR] [\fB-c\fR \fIconf\fR] [\fB-e\fR \fIenv\fR] [\fB-E\fR \fIenv\fR]
  13      [\fB-f\fR \fIflags\fR] [\fB-i\fR \fIname\fR] [\fB-I\fR \fIname\fR] [\fB-g\fR \fIname\fR] [\fB-G\fR \fIname\fR]
  14      [\fB-l\fR \fIdir\fR] [\fB-o\fR \fIdir\fR] [\fB-s\fR \fIdir\fR] [\fB-t\fR [ ELF | AOUT]] [\fB-u\fR] [\fB-v\fR]
  15 .fi
  16 
  17 .SH DESCRIPTION

  18 .LP
  19 The \fBcrle\fR utility provides for the creation and display of a runtime
  20 linking configuration file. The configuration file is read and interpreted by
  21 the runtime linker, \fBld.so.1\fR(1), during process startup. The runtime
  22 linker attempts to read a default configuration file for all processes. For
  23 32-bit processes, the default configuration file is \fB/var/ld/ld.config\fR.
  24 For 64-bit processes, the default configuration file is
  25 \fB/var/ld/64/ld.config\fR.
  26 .sp
  27 .LP
  28 Without any arguments, or with just the \fB-c\fR option, \fBcrle\fR displays
  29 configuration information. This information includes the contents of a
  30 configuration file, any system defaults and the command-line required to
  31 regenerate the configuration file. When used with any other options, a new
  32 configuration file is created or updated.
  33 .sp
  34 .LP
  35 The runtime linker can also be directed to an alternative configuration file by
  36 setting one of the \fBLD_CONFIG\fR family of environment variable.
  37 \fBLD_CONFIG\fR applies to both 32-bit and 64-bit programs. Since 32-bit and
  38 64-bit configuration files differ, a single configuration file cannot be used
  39 for both class of object. Hence, \fBLD_CONFIG\fR can adversely affect program
  40 execution in cases where a program of one class executes a program of the other
  41 class. In particular, it is common practice for the 32-bit version of standard
  42 Solaris utilities to execute their 64-bit counterpart. \fBLD_CONFIG\fR cannot
  43 be successfully used in this case. Therefore, the use of the \fBLD_CONFIG_32\fR
  44 and \fBLD_CONFIG_64\fR environment variables, that precisely target the
  45 appropriate class of process, is recommended.
  46 .sp
  47 .LP
  48 Creating an incorrect configuration file in the standard location,
  49 \fB/var/ld\fR, can prevent programs from running, and can therefore be
  50 difficult to recover from. To guard against this situation, it is recommended
  51 that new configuration files first be created in a temporary location. Then set
  52 the appropriate \fBLD_CONFIG\fR environment variable to this new configuration
  53 file. This setting causes the new configuration file to be used by the runtime
  54 linker instead of any default. After verification, the new configuration file
  55 can be moved to the default location if desired. At any time, the environment
  56 variable \fBLD_NOCONFIG\fR can be set to any value to instruct the runtime
  57 linker to ignore any configuration files. This setting can prove useful during
  58 experimentation.
  59 .sp
  60 .LP
  61 A configuration file can contain the following information.
  62 .sp
  63 .ne 2
  64 .na
  65 \fBDefault Search Paths\fR
  66 .ad
  67 .sp .6
  68 .RS 4n
  69 The runtime linker uses a prescribed search path for locating the dynamic
  70 dependencies of an object. This search path starts with the components of any


 165 system components. When this situation arises the flexibility offered by
 166 dynamic linking system components can be compromised. This type of application
 167 failure can be very difficult to diagnose. No verification of directory cache
 168 information is performed. Any changes to the directory structure are not seen
 169 by a process until the cache is rebuilt.
 170 .sp
 171 .LP
 172 System shared objects are often well tuned, and can show little benefit from
 173 being cached. The directory cache and alternative object features are typically
 174 applicable to user applications and shared objects, and may only show
 175 improvement in some very specific cases.
 176 .sp
 177 .LP
 178 \fBcrle\fR creates alternate objects for the shared objects that are discovered
 179 when using the \fB-I\fR and \fB-G\fR options, using \fBdldump\fR(3C). The
 180 alternate object is created in the directory specified by the preceding
 181 \fB-o\fR option, or defaults to the directory in which the configuration file
 182 is created. The flags used by \fBdldump()\fR are specified using the \fB-f\fR
 183 option, or default to \fBRTLD_REL_RELATIVE\fR.
 184 .SH OPTIONS

 185 .LP
 186 The following options are supported.
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fB-64\fR\fR
 191 .ad
 192 .sp .6
 193 .RS 4n
 194 Specify to process 64-bit objects, the default is 32-bit. Use \fB-64\fR to
 195 create a 64-bit specific configuration file.
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fB-a\fR \fIname\fR\fR
 202 .ad
 203 .sp .6
 204 .RS 4n


 775 \&.....
 776 $ \fBLD_DEBUG=files LD_PRELOAD=preload.so.2 ./main\fR
 777 \&.....
 778 18764: file=preload.so.2;  preloaded
 779 18764: file=/local/lib/preload.so.2  [ ELF ]; generating link map
 780 \&.....
 781 18764: file=preload.so.1;  preloaded
 782 18764: file=/local/lib/preload.so.1  [ ELF ]; generating link map
 783 \&.....
 784 .fi
 785 .in -2
 786 .sp
 787 
 788 .sp
 789 .LP
 790 With this configuration file, a replaceable search path has been specified
 791 together with a permanent preload object which becomes appended to the process
 792 environment definition.
 793 
 794 .SH EXIT STATUS

 795 .LP
 796 The creation or display of a configuration file results in a \fB0\fR being
 797 returned. Otherwise, any error condition is accompanied with a diagnostic
 798 message and a non-zero value being returned.
 799 .SH NOTES

 800 .LP
 801 The ability to tag an alternative application to use an application-specific
 802 configuration file, is possible if the original application contains one of the
 803 \fI\&.dynamic\fR tags \fBDT_FLAGS_1\fR or \fBDT_FEATURE_1\fR. Without these
 804 entries, a configuration file must be specified using the \fBLD_CONFIG\fR
 805 environment variable. Care should be exercised with this latter method as this
 806 environment variable is visible to any forked applications.
 807 .sp
 808 .LP
 809 The use of the \fB-u\fR option requires at least version 2 of \fBcrle\fR. This
 810 version level is evident from displaying the contents of a configuration file.
 811 .sp
 812 .in +2
 813 .nf
 814 $ \fBcrle\fR
 815 
 816 Configuration file [2]: /var/ld/ld.config
 817   ......
 818 .fi
 819 .in -2


 827 option. Although a version 1 configuration file update is possible, the
 828 configuration file contents might be insufficient for \fBcrle\fR to compute the
 829 entire update requirements.
 830 .sp
 831 .LP
 832 Configuration files contain platform specific binary data. A given
 833 configuration file can only be interpreted by software with the same machine
 834 class and byte ordering. However, the information necessary to enforce this
 835 restriction was not included in configuration files until \fBSXCE\fR build
 836 \fB41\fR. As of this \fBSXCE\fR build, configuration files have system
 837 identification information at the beginning of the file. This additional
 838 information is used by \fBcrle\fR and the runtime to check their compatibility
 839 with configuration files. This information also allows the \fBfile\fR(1)
 840 command to properly identify  configuration files. For backward compatibility,
 841 older files that are missing this information are still accepted, although
 842 without the identification and error checking that would otherwise be possible.
 843 When processing an update (\fB-u\fR) operation for an older file that lacks
 844 system information, \fBcrle\fR does not add system identification information
 845 to the result.
 846 .SH FILES

 847 .ne 2
 848 .na
 849 \fB\fB/var/ld/ld.config\fR\fR
 850 .ad
 851 .sp .6
 852 .RS 4n
 853 Default configuration file for 32-bit applications.
 854 .RE
 855 
 856 .sp
 857 .ne 2
 858 .na
 859 \fB\fB/var/ld/64/ld.config\fR\fR
 860 .ad
 861 .sp .6
 862 .RS 4n
 863 Default configuration file for 64-bit applications.
 864 .RE
 865 
 866 .sp


 897 .ne 2
 898 .na
 899 \fB\fB/usr/lib/libcrle.so.1\fR\fR
 900 .ad
 901 .sp .6
 902 .RS 4n
 903 Audit library that is employed to \fBdldump\fR(3C) 32-bit objects.
 904 .RE
 905 
 906 .sp
 907 .ne 2
 908 .na
 909 \fB\fB/usr/lib/64/libcrle.so.1\fR\fR
 910 .ad
 911 .sp .6
 912 .RS 4n
 913 Audit library that is employed to \fBdldump\fR(3C) 64-bit objects.
 914 .RE
 915 
 916 .SH ENVIRONMENT VARIABLES

 917 .LP
 918 There are no environment variables that are referenced by \fBcrle\fR. However,
 919 several environment variables affect the runtime linkers behavior in regard to
 920 the processing of configuration files that are created by \fBcrle\fR.
 921 .sp
 922 .ne 2
 923 .na
 924 \fB\fBLD_CONFIG\fR, \fBLD_CONFIG_32\fR and \fBLD_CONFIG_64\fR\fR
 925 .ad
 926 .sp .6
 927 .RS 4n
 928 Provide an alternative configuration file.
 929 .RE
 930 
 931 .sp
 932 .ne 2
 933 .na
 934 \fB\fBLD_NOCONFIG\fR, \fBLD_NOCONFIG_32\fR and \fBLD_NOCONFIG_64\fR\fR
 935 .ad
 936 .sp .6


 952 .ne 2
 953 .na
 954 \fB\fBLD_NOENVCONFIG\fR, \fBLD_NOENVCONFIG_32\fR and \fBLD_NOENVCONFIG_64\fR\fR
 955 .ad
 956 .sp .6
 957 .RS 4n
 958 Disable environment variable processing from a configuration file.
 959 .RE
 960 
 961 .sp
 962 .ne 2
 963 .na
 964 \fB\fBLD_NOOBJALTER\fR, \fBLD_NOOBJALTER_32\fR and \fBLD_NOOBJALTER_64\fR\fR
 965 .ad
 966 .sp .6
 967 .RS 4n
 968 Disable alternative object processing from a configuration file.
 969 .RE
 970 
 971 .SH ATTRIBUTES

 972 .LP
 973 See \fBattributes\fR(5) for descriptions of the following attributes.
 974 .sp
 975 
 976 .sp
 977 .TS
 978 box;
 979 c | c
 980 l | l .
 981 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 982 _
 983 Interface Stability     Committed
 984 .TE
 985 
 986 .SH SEE ALSO

 987 .LP
 988 \fBfile\fR(1), \fBld\fR(1), \fBld.so.1\fR(1), \fBdldump\fR(3C),
 989 \fBtempnam\fR(3C), \fBattributes\fR(5)
 990 .sp
 991 .LP
 992 \fILinker and Libraries Guide\fR