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
|