.\" Copyright 1993 Mitchum DSouza <m.dsouza@mrc-apu.cam.ac.uk>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified, jmv@lucifer.dorms.spbu.ru, 1999-11-08
.\" Modified, aeb, 2000-04-07
.\" Updated from glibc docs, C. Scott Ananian, 2001-08-25
.\" Modified, aeb, 2001-08-31
.\" Modified, wharms 2001-11-12, remark on white space and example
.\"
.\" Translated into Spanish Wed Mar 11 14:10:24 CET 1998 by
.\"	Gerardo Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Translation revised Wed Apr 19 2000 by Juan Piernas <piernas@ditec.um.es>
.\" Traducción revisada por Miguel Pérez Ibars <mpi79470@alu.um.es> el 3-febrero-2005
.\"
.TH STRPTIME 3 "11 noviembre 2001"  "GNU" "Manual del Programador de Linux"
.SH NOMBRE
strptime \- convierte una cadena de caracteres que representa un
tiempo a una estructura tm
.SH SINOPSIS
.BR "#define _XOPEN_SOURCE" " /* requerido por glibc2 */"
.br
.B #include <time.h>
.sp
.BI "char *strptime(const char *" s ", const char *" format ,
.BI "struct tm *" tm );
.SH DESCRIPCIÓN
La función
.B strptime()
es la función inversa de
.B strftime()
y convierte la cadena de caracteres a la que apunte
.I s
en valores que son almacenados en la estructura
.B tm
a la que apunte
.IR tm ,
utilizando el formato especificado por
.IR format .
.I format
es una cadena de caracteres que consiste en descriptores de campos y
caracteres de texto, una reminiscencia de
.BR scanf (3).
Cada descriptor de campo consiste en un carácter de porcentaje
.B %
seguido por otro carácter que especifica el reemplazo para el
descriptor de campo.
Todos los otros caracteres de la cadena
.I format
deben tener un carácter concordante en la cadena de entrada, salvo los
espacios en blanco que pueden concordar con cero
o más espacios en blanco de la cadena de entrada.
Entre dos descriptores de campo cualesquiera debe haber siempre
un espacio en blanco o bien otros caracteres alfanuméricos.
.PP
La función \fBstrptime()\fP procesa la cadena de entrada de izquierda a
derecha. Cada uno de los tres posibles elementos de entrada (espacio en
blanco, literal o formato) se tratan uno detrás de otro. Si no se puede
hacer coincidir la entrada con la cadena de formato, la función se detiene.
El resto de las cadenas de formato y de entrada no se procesa.
.PP
Los descriptores de campo de entrada se listan a continuación.
En caso de que la concordancia sea con cadenas de texto (como
el nombre de un día de la semana o de un mes), la comparación
no tiene en cuenta las mayúsculas. En caso de que la concordancia
sea con números, se permite poner ceros al principio aunque no
es obligatorio.
.TP
.B %%
El carácter
.B %.
.TP
.BR %a " o " %A
El nombre del día de la semana según la localización actual,
en forma abreviada o completa.
.TP
.BR %b " o " %B " o " %h
El nombre del mes según la localización actual,
en forma abreviada o completa.
.TP
.B %c
La representación de fecha y hora para la localización actual.
.TP
.B %C
El número de siglo (0-99).
.TP
.BR %d " o " %e
El día del mes (1-31).
.TP
.B %D
Equivalente a %m/%d/%y. (Este es el estilo americano para las fechas, muy confuso 
para los no americanos, especialmente debido a que el formato %d/%m/%y es el que se 
usa ampliamente en Europa.
El formato del estándar ISO 8601 es %Y-%m-%d.)
.TP
.BR %H
La hora (0-23).
.TP
.BR %I
La hora en formato de 12 horas (1-12).
.TP
.B %j
El número de día del año (1-366).
.TP
.B %m
El número de mes (1-12).
.TP
.B %M
El minuto (0-59).
.TP
.B %n
Cadena arbitraria de espacios en blanco.
.TP
.B %p
El equivalente de AM o PM en la localización. (Nota: puede no existir.)
.TP
.B %r
La hora en formato de 12 horas (usando el equivalente de AM o PM en la localización).
En la localización POSIX equivale a %I:%M:%S %p.
Si el campo \fIt_fmt_ampm\fP está vacío en la categoría LC_TIME de la localización
actual el comportamiento es indefinido.
.TP
.B %R
Equivalente a %H:%M.
.TP
.B %S
El segundo (0-60; 60 puede darse para segundos de salto (leap seconds); anteriormente 
también se permitía 61).
.TP
.B %t
Cadena arbitraria de espacios en blanco.
.TP
.B %T
Equivalente a %H:%M:%S.
.TP
.B %U
El número de semana tomando el domingo como primer día de la semana (0-53).
El primer domingo de enero es el primer día de la semana 1.
.TP
.B %w
El número de día de la semana (0-6) con domingo = 0.
.TP
.B %W
El número de semana tomando el lunes como primer día de la semana (0-53).
El primer lunes de enero es el primer día de la semana 1.
.TP
.B %x
La fecha, usando el formato de fecha de la localización.
.TP
.B %X
La hora, usando el formato de hora de la localización.
.TP
.B %y
El año dentro del siglo (0-99).
Cuando no se especifica el siglo, los valores comprendidos en el rango
69-99 se refieren al siglo 20 (1969-1999) y los valores comprendidos en el
rango 00-68 se refieren al siglo 21 (2000-2068).
.TP
.B %Y
El año, incluyendo el siglo (por ejemplo, 1991).
.LP
Algunos descriptores de campo pueden ser modificados por los caracteres
modificadores E u O para indicar el uso de un formato o especificación
alternativo. Si el formato o especificación alternativo no existe en la localización
actual, se utiliza el descriptor de campo sin modificar.
.LP
El modificador E especifica que la cadena de entrada puede contener
versiones alternativas de la representación de fecha y hora dependientes
de la localización:
.TP
.B %Ec
La representación alternativa de fecha y hora de la localización.
.TP
.B %EC
El nombre del año base (período) en la representación alternativa de la localización.
.TP
.B %Ex
La representación alternativa de fecha de la localización.
.TP
.B %EX
La representación alternativa de hora de la localización.
.TP
.B %Ey
El desplazamiento desde %EC (sólo año) en la representación alternativa de la localización.
.TP
.B %EY
La representación alternativa completa para el año.
.LP
El modificador O especifica que la entrada numérica puede estar en
un formato alternativo dependiente de la localización:
.TP
.BR %Od " o " %Oe
El día del mes usando los símbolos numéricos alternativos de la localización;
los ceros del comienzo están permitidos pero no son obligatorios.
.TP
.B %OH
La hora (foramto 24 horas) usando los símbolos numéricos alternativos de la localización.
.TP
.B %OI
La hora (foramto 12 horas) usando los símbolos numéricos alternativos de la localización.
.TP
.B %Om
El mes usando los símbolos numéricos alternativos de la localización.
.TP
.B %OM
Los minutos usando los símbolos numéricos alternativos de la localización.
.TP
.B %OS
Los segundos usando los símbolos numéricos alternativos de la localización.
.TP
.B %OU
El número de semana del año (tomando el domingo como primer día de la semana)
usando los símbolos numéricos alternativos de la localización.
.TP
.B %Ow
El número del día de la semana (domingo=0) usando los símbolos numéricos alternativos 
de la localización.
.TP
.B %OW
El número de semana del año (tomando el lunes como primer día de la semana)
usando los símbolos numéricos alternativos de la localización.
.TP
.B %Oy
El año (desplazamiento desde %C) usando los símbolos numéricos alternativos de 
la localización.
.LP
La estructura de tiempo descompuesto \fItm\fP se define en \fI<time.h>\fP
como sigue:
.sp
.RS
.nf
.ne 12
.ta 8n 16n 32n
struct tm {
	int	tm_sec;			/* segundos */
	int	tm_min;			/* minutos */
	int	tm_hour;		/* horas */
	int	tm_mday;		/* día del mes */
	int	tm_mon;			/* mes */
	int	tm_year;		/* año */
	int	tm_wday;		/* día de la semana */
	int	tm_yday;		/* día del año */
	int	tm_isdst;		/* ¿cambio horario? */
};
.ta
.fi
.RE
.SH "VALOR DEVUELTO"
El valor devuelto por la función es un puntero al primer carácter no
procesado en esta llamada a la función. En el caso de que la cadena de
entrada contenga más caracteres de los que necesita la cadena de formato,
el valor devuelto apunta justo después del último carácter de entrada
consumido. En el caso de que se consuma toda la cadena de entrada, el valor
devuelto apunta al byte NUL al final de la cadena. Si \fBstrptime()\fP no
puede hacer coincidir toda la cadena de formato y, por tanto, se ha
producido un error, la función devuelve \fBNULL\fP.
.SH "CONFORME A"
XPG4, SUSv2, POSIX 1003.1-2001.
.SH EJEMPLO
El siguiente ejemplo demuestra el uso de \fBstrptime()\fP
y \fBstrftime()\fP.
.sp
.nf
.ne 12
.ta 8n 16n
#include <stdio.h>
#include <time.h>

int main() {
	struct tm tm;
	char buf[255];

	strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
	strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
	puts(buf);
	return 0;
}
.ta
.fi
.SH "EXTENSIONES DE GNU"
Por razones de simetría, glibc trata de dar soporte en
.B strptime
a los mismos caracteres de formato que para
.BR strftime.
(En la mayoría de casos se analizan los campos correspondientes,
pero no se modifica ningún campo de la estructura \fItm\fP.)
Esto conduce a
.TP
.B %F
Equivalente a \fB%Y-%m-%d\fP, el formato de fecha de ISO 8601.
.TP
.B %g
El año correspondiente al número de semana ISO, pero sin el siglo (0-99).
.TP
.B %G
El año correspondiente al número de semana ISO. (Por ejemplo, 1991.)
.TP
.B %u
El día de la semana como un número decimal (1-7, donde lunes = 1).
.TP
.B %V
El número de semana ISO 8601:1988 como un número decimal (1-53).
Si la semana (comenzando en lunes) que contiene el 1 de enero tiene cuatro o más
días en el nuevo año, se considera la semana 1. En otro caso, se toma como la última 
semana del año anterior y la siguiente semana pasa a ser la semana 1.
.TP
.B %z
Una especificación estándar RFC-822/ISO 8601 de huso horario.
.TP
.B %Z
El nombre del huso horario.
.LP
De manera similar, debido a las extensiones hechas por GNU a \fIstrftime\fP,
se acepta %k como sinónimo de %H, %l debería ser aceptado como sinónimo de
%I y %P se acepta como sinónimo de %p.
Finalmente
.TP
.B %s
El número de segundos desde la época, es decir, desde la media noche del
1 de enero de 1970 (1970-01-01 00:00:00 UTC).
Los segundos de salto (leap seconds) no se tienen en cuenta a menos que
se encuentre disponible el soporte para segundos de salto.
.LP
La implementación de libc de GNU no requiere que haya espacios en
blanco entre dos descriptores de campo.
.SH OBSERVACIONES
.LP
En principio, esta función no inicializa la estructura \fBtm\fP sino que simplemente
almacena los valores especificados.
Esto quiere decir que la estructura \fBtm\fP debe ser inicializada antes de la llamada.
Los detalles pueden diferir ligeramente entre diferentes sistemas Unix.
La implementación de libc de GNU no modifica aquellos campos que no son
especificados explícitamente, salvo los campos
.IR tm_wday
y
.IR tm_yday 
que son recalculados si cualquiera de los elementos año, mes o día son alterados.
.PP
Esta función está disponible desde la versión 4.6.8 de libc.
Los ficheros de cabecera de libc4 y libc5 en Linux definen el prototipo de manera 
incondicional; los ficheros de cabecera de glibc2 definen el prototipo solamente cuando
_XOPEN_SOURCE o _GNU_SOURCE están definidas.
.PP
En versiones de libc anteriores a la 5.4.13 los espacios en blanco (y las 
especificaciones 'n' y 't') no eran manejados, no se aceptaban los modificadores de 
localización 'E' y 'O', y la especificación 'C' era un sinónimo de la especificación 'c'.
.PP
La especificación 'y' (año en el siglo) es considerada un año
en el siglo 20 por libc4 y libc5. En la versión 2.0 de glibc se considera
un año en el rango 1950-2049. Finalmente, en la versión 2.1 de glibc la
especificación 'y' se considera un año en el rango 1969-2068.
.\" In libc4 and libc5 the code for %I is broken (fixed in glibc;
.\" %OI was fixed in glibc 2.2.4).
.SH "VÉASE TAMBIÉN"
.BR time (2),
.BR getdate (3),
.BR scanf (3),
.BR setlocale (3),
.BR strftime (3)