NOMBRE

       regcomp, regexec, regerror, regfree - funciones para expresiones regulares POSIX

SINOPSIS

       #include <sys/types.h>
       #include <regex.h>

       int regcomp(regex_t *preg, const char *regex, int cflags);
       int regexec(const  regex_t  *preg, const char *string, size_t nmatch, regmatch_t pmatch[],
                   int eflags);
       size_t regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size);
       void regfree(regex_t *preg);

COMPILACIÓN DE EXPRESIONES REGULARES POSIX

       regcomp se utiliza para compilar una expresión regular en un formato  apropiado  para  ser
       usado por regexec en búsquedas posteriores.

       A  regcomp  se  le  pasan  como  parámetros  preg,  un puntero a un área de almacenamiento
       temporal de patrones, regex, un puntero a una cadena  terminada  en  un  carácter  nulo  y
       cflags, banderas utilizadas para determinar el tipo de compilación.

       Toda  búsqueda  con  expresiones regulares se debe realizar mediante un buffer de patrones
       compilados, por tanto, a regexec siempre se le debe proporcionar la dirección de un buffer
       de patrones inicializado mediante regcomp.

       cflags debe ser un O-lógico a nivel de bits de una o más de las siguientes opciones:

       REG_EXTENDED
              Utilizar  el  tipo  de  sintaxis  'Expresión  Regular  Extendida  POSIX'  cuando se
              interprete regex.  Si no se activa esta opción, se  utiliza  el  tipo  de  sintaxis
              'Expresión Regular Básica POSIX'.

       REG_ICASE
              No  distinguir  entre mayúsculas y minúsculas. Las siguientes búsquedas regexec que
              usen este buffer de patrones no distinguirán entre mayúsculas y minúsculas.

       REG_NOSUB
              No se necesita soporte para obtener las posiciones de subcadenas coincidentes.  Los
              parámetros  nmatch  y  pmatch  de  regexec  se  ignoran  si  el  buffer de patrones
              proporcionado se compiló con esta opción.

       REG_NEWLINE
              Los operadores "coincidir con cualquier carácter"  no  coinciden  con  un  carácter
              "nueva línea".

              Una lista de no-coincidencia ([^...])  que no contenga un carácter "nueva línea" no
              coincidirá con una "nueva línea".

              Un operador "coincidir al principio de línea" (^)  coincide  con  la  cadena  vacía
              inmediatamente  posterior  a  un  carácter  "nueva  línea",  sin tener en cuenta si
              eflags, la bandera de ejecución de regexec, contiene REG_NOTBOL o no.

              Un operador "coincidir al  final  de  línea"  ($)  coincide  con  la  cadena  vacía
              inmediatamente  anterior a un carácter "nueva línea", sin tener en cuenta si eflags
              contiene REG_NOTEOL o no.

COINCIDENCIAS EN LAS EXPRESIONES REGULARES POSIX

       regexec se utiliza para comprobar si una cadena string, terminada  en  un  carácter  nulo,
       coincide  con  alguno  de  los patrones precompilados del buffer preg.  nmatch y pmatch se
       utilizan para informar respecto a la localización de cualquier coincidencia.  eflags puede
       ser   REG_NOTBOL  o  REG_NOTEOL  o  un  O-lógico  de  ambos  valores,  lo  que  cambia  el
       comportamiento en las coincidencias tal como se describe a continuación.

       REG_NOTBOL
              El operador "coincidir al principio de línea" siempre falla  en  las  coincidencias
              (pero  vea la opción de compilación REG_NEWLINE más arriba).  Esta bandera se puede
              utilizar cuando se pasan diferentes porciones de una cadena a regexec y el comienzo
              de la cadena no se debe interpretar como el principio de una línea.

       REG_NOTEOL
              El  operador  "coincidir al final de línea" siempre falla en la coincidencias (pero
              vea la opción de compilación REG_NEWLINE más arriba).

   DESPLAZAMIENTOS DE BYTES
       A menos que se especificara REG_NOSUB en la compilación del buffer de patrones, es posible
       obtener  información  sobre  la posición de subcadenas coincidentes.  pmatch debe tener un
       tamaño de al menos nmatch elementos.  Estos  se  rellenan  al  ejecutar  regexec  con  las
       posiciones  de  cadenas  coincidentes.  Cualquier  elemento  de la estructura no utilizado
       contendrá el valor -1.

       La estructura regmatch_t, que es el tipo de pmatch, se define en regex.h.

              typedef struct
              {
                regoff_t rm_so;
                regoff_t rm_eo;
              } regmatch_t;

       Cada elemento rm_so que no es -1 indica el  principio  de  la  siguiente  mayor  subcadena
       coincidente  dentro  de  la  cadena.  El  elemento  relativo  rm_eo  indica el final de la
       coincidencia.

INFORMES DE ERROR POSIX

       regerror se utiliza para convertir los códigos de error que pueden devolver tanto  regcomp
       como regexec en cadenas de mensaje de error.

       A  regerror se le pasa el código de error, errcode, el buffer de patrones preg, un puntero
       al buffer de una cadena de caracteres, errbuf, y  el  tamaño  del  buffer  de  la  cadena,
       errbuf_size.   Devuelve  el  tamaño  de  errbuf  necesario  para contener la cadena con el
       mensaje de error terminada en un carácter nulo. Si tanto errbuf como  errbuf_size  no  son
       cero, errbuf se rellena con los primeros errbuf_size - 1 caracteres del mensaje de error y
       un carácter nulo terminador.

LIBERACIÓN DE BUFFERS DE PATRONES POSIX

       Si a regfree se le pasa un buffer de patrones precompilados,  preg,  liberará  la  memoria
       del buffer de patrones reservada por el proceso de compilación, regcomp.

VALOR DEVUELTO

       regcomp devuelve cero si la compilación tiene éxito y un código de error si falla.

       regexec devuelve cero si hay coincidencia y REG_NOMATCH en caso de fallo.

ERRORES

       regcomp puede devolver los siguientes errores:

       REG_BADRPT
              Uso  incorrecto  de  operadores  de  repetición,  como  el  uso  de `*' como primer
              carácter.

       REG_BADBR
              Uso incorrecto del operador de referencia inversa.

       REG_EBRACE
              Existe una llave de un operador de intervalo no emparejada.

       REG_EBRACK
              Existe un corchete de un operador de lista no emparejado.

       REG_ERANGE
              Uso incorrecto de un operador de rango; por ejemplo, el límite superior  del  rango
              ocurre antes que el límite inferior.

       REG_ECTYPE
              Nombre de clase de caracteres desconocido.

       REG_ECOLLATE
              Elemento de comparación inválido.

       REG_EPAREN
              Existe un paréntesis de un operador de grupo no emparejado.

       REG_ESUBREG
              Referencia inversa incorrecta a una subexpresión.

       REG_EEND
              Error indefinido. No definido por POSIX.2.

       REG_EESCAPE
              Barra invertida (\) al final.

       REG_BADPAT
              Uso incorrecto de operadores de patrón tales como grupo o lista.

       REG_ESIZE
              La  expresión  regular  compilada necesita un buffer de patrones mayor que 64Kb. No
              definido por POSIX.2.

       REG_ESPACE
              Las rutinas de expresiones regulares se ejecutaron fuera de sus límites de memoria.

CONFORME A

       POSIX.2

VÉASE TAMBIÉN

       regex(7), El manual de expresiones regulares de GNU