Compaq C
Compaq C
Run-Time Library Reference Manual for
OpenVMS Systems
strdup
Finds and points to a duplicate string.
Format
#include <string.h>
char *strdup (const char *s1);
Function Variants This function also has variants named
_strdup32
and
_strdup64
for use with 32-bit and 64-bit pointer sizes, respectively. See
Section 1.10 for more information on using pointer-size-specific
functions.
Arguments
s1
The first of two strings to compare.
Description
This function returns a pointer to a string that is an exact duplicate
of the string pointed to by s1. The
malloc
function is used to allocate space for the new string. The
strdup function is provided for compatibility with existing
systems.
Return Values
|
x
|
A pointer to the resulting string.
|
|
NULL
|
Indicates an error.
|
strerror
Maps the error number in error_code to a locale-dependent
error message string.
Format
#include <string.h>
char *strerror (int error_code); (ANSI C)
char *strerror (int error_code[, int
vms_error_code]); (COMPAQ C EXTENSION)
Arguments
error_code
An error code.
vms_error_code
An OpenVMS error code.
Description
This function uses the error number in error_code to retrieve
the appropriate locale-dependent error message. The contents of the
error message strings are determined by the LC_MESSAGES category of the
program's current locale.
When a program is not compiled with any standards-related feature-test
macros (see Section 1.5.1),
strerror
has a second argument (vms_error_code), which is used in the
following way:
- If error_code is EVMSERR and there is a second argument,
then that second argument is used as the
vaxc$errno
value.
- If error_code is EVMSERR and there is no second argument,
look at
vaxc$errno
to get the OpenVMS error condition.
See the
strerror
example.
Use of the second argument is not included in the ANSI C definition of
strerror
and is, therefore, not portable.
Because no return value is reserved to indicate an error, applications
should set the value of
errno
to 0, call
strerror
, and then test the value of
errno
; a nonzero value indicates an error condition.
Return Values
|
x
|
A pointer to a buffer containing the appropriate error message. Do not
modify this buffer in your programs. Moreover, calls to the
strerror
function may overwrite this buffer with a new message.
|
Example
#include <stdio.h>
#include <errno.h>
#include <string.h>
#include <stdlib.h>
#include <ssdef.h>
main()
{
puts(strerror(EVMSERR));
errno = EVMSERR;
vaxc$errno = SS$_LINKEXIT;
puts(strerror(errno));
puts(strerror(EVMSERR, SS$_ABORT));
exit(1);
}
|
Running this example produces the following output:
non-translatable vms error code: <none>
network partner exited
abort
|
strfmon
Converts a number of monetary values into a string. The conversion is
controlled by a format string.
Format
#include <monetary.h>
ssize_t strfmon (char *s, size_t maxsize, const char
*format, ...);
Arguments
s
A pointer to the resultant string.
maxsize
The maximum number of bytes to be stored in the resultant string.
format
A pointer to a string that controls the format of the output string.
...
The monetary values of type
double
that are to be formatted for the output string. There should be as many
values as there are conversion specifications in the format string
pointed to by format. The function fails if there are
insufficient values. Excess arguments are ignored.
Description
This function creates a string pointed to by s, using the
monetary values supplied. A maximum of maxsize bytes is copied
to s.
The format string pointed to by format consists of ordinary
characters and conversion specifications. All ordinary characters are
copied unchanged to the output string. A conversion specification
defines how one of the monetary values supplied is formatted in the
output string.
A conversion specification consists of a percent character (%),
followed by a number of optional characters (see Table REF-5), and
concluding with a conversion specifier (see Table REF-6).
If any of the optional characters listed in Table REF-5 is included
in a conversion specification, they must appear in the order shown.
Table REF-5 Optional Characters in strfmon Conversion Specifications
| Character |
Meaning |
|
=
character
|
Use
character as the numeric fill character if a left precision is
specified. The default numeric fill character is the space character.
The fill character must be representable as a single byte in order to
work with precision and width count. This conversion specifier is
ignored unless a left precision is specified, and it does not affect
width filling, which always uses the space character.
|
|
^
|
Do not use separator characters to format the number. By default, the
digits are grouped according to the
mon_grouping field in the LC_MONETARY category of the current
locale.
|
|
+
|
Add the string specified by the
positive_sign or
negative_sign fields in the current locale. If
p_sign_posn or
n_sign_posn is set to zero, then parentheses are used by
default to indicate negative values. Otherwise, sign strings are used
to indicate the sign of the value. You cannot use a + and a ( in the
same conversion specification.
|
|
(
|
Enclose negative values within parentheses. The default is taken from
the
p_sign_posn and
n_sign_posn fields in the current locale. If
p_sign_posn or
n_sign_posn is set to zero, then parentheses are used by
default to indicate negative values. Otherwise, sign strings are used
to indicate the sign of the value. You cannot use a + and ( in the same
conversion specification.
|
|
!
|
Suppress the currency symbol. By default, the currency symbol is
included.
|
|
--
|
Left-justify the value within the field. By default, values are
right-justified.
|
|
field width
|
A decimal integer that specifies the minimum field width in which to
align the result of the conversion. The default field width is the
smallest field that can contain the result.
|
|
#left_precision
|
A # followed by a decimal integer specifies the number of digits to the
left of the radix character. Extra positions are filled by the fill
character. By default the precision is the smallest required for the
argument. If grouping is not suppressed with the ^ conversion
specifier, and if grouping is defined for the current locale, grouping
separators are inserted before any fill characters are added. Grouping
separators are not applied to fill characters even if the fill
character is defined as a digit.
|
|
.right_precision
|
A period (.) followed by a decimal integer specifies the number of
digits to the right of the radix character. Extra positions are filled
with zeros. The amount is rounded to this number of decimal places. If
the right precision is zero, the radix character is not included in the
output. By default the right precision is defined by the
frac_digits or
int_frac_digits field of the current locale.
|
Table REF-6 strfmon Conversion Specifiers
| Specifier |
Meaning |
|
i
|
Use the international currency symbol defined by the
int_currency_symbol field in the current locale, unless the
currency symbol has been suppressed.
|
|
n
|
Use the local currency symbol defined by the
currency_symbol field in the current locale, unless the
currency symbol has been suppressed.
|
|
%
|
Output a % character. The conversion specification must be %%; none of
the optional characters is valid with this specifier.
|
Return Values
|
x
|
The number of bytes written to the string pointed to by
s, not including the null terminating character.
|
|
--1
|
Indicates an error.The function sets
errno
to one of the following values:
- EINVAL -- A conversion specification is syntactically incorrect.
- E2BIG -- Processing the complete format string would produce more
than
maxsize bytes.
|
Example
#include <stdlib.h>
#include <stdio.h>
#include <locale.h>
#include <monetary.h>
#include <errno.h>
#define MAX_BUF_SIZE 124
main()
{
size_t ret;
char buffer[MAX_BUF_SIZE];
double amount = 102593421;
/* Display a monetary amount using the en_US.ISO8859-1 */
/* locale and a range of different display formats. */
if (setlocale(LC_ALL, "en_US.ISO8859-1") == (char *) NULL) {
perror("setlocale");
exit(EXIT_FAILURE);
}
ret = strfmon(buffer, MAX_BUF_SIZE, "International: %i\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_SIZE, "National: %n\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_SIZE, "National: %=*#10n\n", amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_SIZE, "National: %(n\n", -1 * amount);
printf(buffer);
ret = strfmon(buffer, MAX_BUF_SIZE, "National: %^!n\n", amount);
printf(buffer);
}
|
Running the example program produces the following result:
International: USD 102,593,421.00
National: $102,593,421.00
National: $**102,593,421.00
National: ($102,593,421.00)
National: 102593421.00
|
strftime
Uses date and time information stored in a
tm
structure, to create an output string. The format of the output string
is controlled by a format string.
Format
#include <time.h>
size_t strftime (char *s, size_t maxsize, const char
*format, const struct tm *timeptr);
Function Variants Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE
feature-test macros defined enables a local-time-based entry point to
this function that is equivalent to the behavior before OpenVMS Version
7.0.
Arguments
s
A pointer to the resultant string.
maxsize
The maximum number of bytes to be stored in the resultant string,
including the null terminator.
format
A pointer to a string that controls the format of the output string.
timeptr
A pointer to the local time (
tm
) structure. The
tm
structure is defined in the
<time.h>
header file.
Description
This function uses data in the structure pointed to by timeptr
to create the string pointed to by s. A maximum of
maxsize bytes is copied to s.
The format string consists of zero or more conversion specifications
and ordinary characters. All ordinary characters (including the
terminating null character) are copied unchanged into the output
string. A conversion specification defines how data in the
tm
structure is formatted in the output string.
A conversion specification consists of a percent (%) character followed
by one or more optional characters (see Table REF-7), and concluding
with a conversion specifier (see Table REF-8). If any of the
optional characters listed in Table REF-7 are specified, they must
appear in the order shown in the table.
The
strftime
function behaves as if it called
tzset
.
Table REF-7 Optional Elements of strftime Conversion Specifications
| Element |
Meaning |
|
--
|
Optional with the field width to specify that the field is
left-justified and padded with spaces. This cannot be used with the 0
element.
|
|
0
|
Optional with the field width to specify that the field is
right-justified and padded with zeros. This cannot be used with the --
element.
|
|
field width
|
A decimal integer that specifies the maximum field width
|
|
.precision
|
A decimal integer that specifies the precision of data in a field.
For the d, H, I, j, m, M, o, S, U, w, W, y and Y conversion
specifiers, the precision specifier is the minimum number of digits to
appear in the field. If the conversion specification has fewer digits
than that specified by the precision, leading zeros are added.
For the a, A, b, B, c, D, E, h, n, N, p, r, t, T, x, X, Z, and %
conversion specifiers, the precision specifier is the maximum number of
characters to appear in the field. If the conversion specification has
more characters than that specified by the the precision, characters
are truncated on the right.
The default precision for the d, H, I, m, M, o, S, U, w, W, y and Y
conversion specifiers is 2; the default precision for the j conversion
specifier is 3.
|
Note that the list of conversion specifications in Table REF-7 are
extensions to the XPG4 specification.
Table REF-8 lists the conversion specifiers. The
strftime
function uses fields in the LC_TIME category of the program's current
locale to provide a value. For example, if %B is specified, the
function accesses the mon field in LC_TIME to find the full
month name for the month specified in the tm structure. The result of
using invalid conversion specifiers is undefined.
Table REF-8 strftime Conversion Specifiers
| Specifier |
Replaced by |
|
a
|
The locale's abbreviated weekday name
|
|
A
|
The locale's full weekday name
|
|
b
|
The locale's abbreviated month name
|
|
B
|
The locale's full month name
|
|
c
|
The locale's appropriate date and time representation
|
|
C
|
The century number (the year divided by 100 and truncated to an
integer) as a decimal number (00 -- 99)
|
|
d
|
The day of the month as a decimal number (01 -- 31)
|
|
D
|
Same as %m/%d/%y
|
|
e
|
The day of the month as a decimal number (1 -- 31) in a 2 digit field
with the leading space character fill
|
|
Ec
|
The locale's alternative date and time representation
|
|
EC
|
The name of the base year (period) in the locale's alternative
representation
|
|
Ex
|
The locale's alternative date representation
|
|
EX
|
The locale's alternative time representation
|
|
Ey
|
The offset from the base year (%EC) in the locale's alternative
representation
|
|
EY
|
The locale's full alternative year representation
|
|
h
|
Same as %b
|
|
H
|
The hour (24-hour clock) as a decimal number (00 -- 23)
|
|
I
|
The hour (12-hour clock) as a decimal number (01 -- 12)
|
|
j
|
The day of the year as a decimal number (001 -- 366)
|
|
m
|
The month as a decimal number (01 -- 12)
|
|
M
|
The minute as a decimal number (00 -- 59)
|
|
n
|
The newline character
|
|
Od
|
The day of the month using the locale's alternative numeric symbols
|
|
Oe
|
The date of the month using the locale's alternative numeric symbols
|
|
OH
|
The hour (24-hour clock) using the locale's alternative numeric symbols
|
|
OI
|
The hour (12-hour clock) using the locale's alternative numeric symbols
|
|
Om
|
The month using the locale's alternative numeric symbols
|
|
OM
|
The minutes using the locale's alternative numeric symbols
|
|
OS
|
The seconds using the locale's alternative numeric symbols
|
|
Ou
|
The weekday as a number in the locale's alternative representation
(Monday=1)
|
|
OU
|
The week number of the year (Sunday as the first day of the week) using
the locale's alternative numeric symbols
|
|
OV
|
The week number of the year (Monday as the first day of the week) as a
decimal number (01 --53) using the locale's alterntative numeric
symbols. If the week containing January 1 has four or more days in the
new year, it is considered as week 1. Otherwise, it is considered as
week 53 of the previous year, and the next week is week 1.
|
|
Ow
|
The weekday as a number (Sunday=0) using the locale's alternative
numeric symbols
|
|
OW
|
The week number of the year (Monday as the first day of the week) using
the locale's alternative numeric symbols
|
|
Oy
|
The year without the century using the locale's alternative numeric
symbols
|
|
p
|
The locale's equivalent of the AM/PM designations associated with a
12-hour clock
|
|
r
|
The time in AM/PM notation
|
|
R
|
The time in 24-hour notation (%H:%M)
|
|
S
|
The second as a decimal number (00 -- 61)
|
|
t
|
The tab character
|
|
T
|
The time (%H:%M:%S)
|
|
u
|
The weekday as a decimal number between 1 and 7 (Monday=1)
|
|
U
|
The week number of the year (the first Sunday as the first day of week
1) as a decimal number (00 -- 53)
|
|
V
|
The week number of the year (Monday as the first day of the week) as a
decimal number (00 -- 53). If the week containing January 1 has four or
more days in the new year, it is considered as week 1. Otherwise, it is
considered as week 53 of the previous year, and the next week is week 1.
|
|
w
|
The weekday as a decimal number (0 [Sunday] -- 6)
|
|
W
|
The week number of the year (the first Monday as the first day of week
1) as a decimal number (00 -- 53)
|
|
x
|
The locale's appropriate date representation
|
|
X
|
The locale's appropriate time representation
|
|
y
|
The year without century as a decimal number (00 -- 99)
|
|
Y
|
The year with century as a decimal number
|
|
Z
|
Time-zone name or abbreviation. If time-zone information is not
available, no character is output.
|
|
%
|
%
|
Return Values
|
x
|
The number of characters placed into the array pointed to by
s, not including the terminating null character.
|
|
0
|
Indicates an error occurred. The contents of the array are
indeterminate.
|
Example
#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <locale.h>
#include <errno.h>
#define NUM_OF_DATES 7
#define BUF_SIZE 256
/* This program formats a number of different dates, once */
/* using the C locale and then using the fr_FR.ISO8859-1 */
/* locale. Date and time formatting is done using strftime(). */
main()
{
int count,
i;
char buffer[BUF_SIZE];
struct tm *tm_ptr;
time_t time_list[NUM_OF_DATES] =
{500, 68200000, 694223999, 694224000,
704900000, 705000000, 705900000};
/* Display dates using the C locale */
printf("\nUsing the C locale:\n\n");
setlocale(LC_ALL, "C");
for (i = 0; i < NUM_OF_DATES; i++) {
/* Convert to a tm structure */
tm_ptr = localtime(&time_list[i]);
/* Format the date and time */
count = strftime(buffer, BUF_SIZE,
"Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr);
if (count == 0) {
perror("strftime");
exit(EXIT_FAILURE);
}
/* Print the result */
printf(buffer);
}
/* Display dates using the fr_FR.ISO8859-1 locale */
printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n");
setlocale(LC_ALL, "fr_FR.ISO8859-1");
for (i = 0; i < NUM_OF_DATES; i++) {
/* Convert to a tm structure */
tm_ptr = localtime(&time_list[i]);
/* Format the date and time */
count = strftime(buffer, BUF_SIZE,
"Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr);
if (count == 0) {
perror("strftime");
exit(EXIT_FAILURE);
}
/* Print the result */
printf(buffer);
}
}
|
Running the example program produces the following result:
Using the C locale:
Date: Thursday 01 January 1970
Time: 00:08:20
Date: Tuesday 29 February 1972
Time: 08:26:40
Date: Tuesday 31 December 1991
Time: 23:59:59
Date: Wednesday 01 January 1992
Time: 00:00:00
Date: Sunday 03 May 1992
Time: 13:33:20
Date: Monday 04 May 1992
Time: 17:20:00
Date: Friday 15 May 1992
Time: 03:20:00
Using the fr_FR.ISO8859-1 locale:
Date: jeudi 01 janvier 1970
Time: 00:08:20
Date: mardi 29 février 1972
Time: 08:26:40
Date: mardi 31 décembre 1991
Time: 23:59:59
Date: mercredi 01 janvier 1992
Time: 00:00:00
Date: dimanche 03 mai 1992
Time: 13:33:20
Date: lundi 04 mai 1992
Time: 17:20:00
Date: vendredi 15 mai 1992
Time: 03:20:00
|
|
