m4(1p)

m4(1p) – POSIX-manualsida

PROLOG

Denna manualsida är en del av POSIX Programmer's Manual. Linux-implementationen av detta gränssnitt kan skilja sig åt. Se motsvarande Linux-manualsida för detaljer om Linux-beteende, eller notera att gränssnittet kanske inte är implementerat på Linux.

NAMN

m4 — makroprocessor

SYNOPSIS

m4 [-s] [-D namn[=värde]]... [-U namn]... fil...

BESKRIVNING

Verktyget m4 är en makroprocessor som läser en eller flera textfiler, bearbetar dem enligt de makrosatser som finns i filerna och skriver resultatet till standard ut.

FLAGGOR

Verktyget m4 ska följa Base Definitions-volymen av POSIX.1-2017, avsnitt 12.2, Utility Syntax Guidelines, med undantaget att ordningen för flaggorna -D och -U är betydelsefull, och att flaggor kan blandas med operander.

Följande flaggor ska stödjas:

-s

Aktivera radsynkroniseringsutdata för förprocessningsfasen i c99, det vill säga direktiv av typen #line.

-D namn[= värde]

Definiera namn till värde, eller till tomt värde om = värde utelämnas.

-U namn

Avdefiniera namn.

OPERANDER

Följande operand ska stödjas:

fil

Sökvägen till en textfil som ska bearbetas. Om ingen fil anges, eller om filen är -, ska standard in läsas.

STANDARD IN

Standard in ska vara en textfil som används om ingen fil-operand anges, eller om operanden är -.

INDATAFILER

Indatafilen som anges av operanden fil ska vara en textfil.

MILJÖVARIABLER

Följande miljövariabler ska påverka körningen av m4:

LANG

Anger ett standardvärde för internationaliseringsvariabler som är odefinierade eller tomma. Se Base Definitions-volymen av POSIX.1-2017, avsnitt 8.2, Internationalization Variables, för företrädesordningen mellan internationaliseringsvariabler som används för att bestämma värdena för lokalkategorier.

LC_ALL

Om denna är satt till ett icke-tomt strängvärde åsidosätts värdena för alla andra internationaliseringsvariabler.

LC_CTYPE

Bestämmer lokalen för tolkning av byteföljder i textdata som tecken, till exempel skillnaden mellan enkelbyte- och multibytetecken i argument och indatafiler.

LC_MESSAGES

Bestämmer vilken lokal som ska användas för formatet och innehållet i diagnostiska meddelanden som skrivs till standard fel.

NLSPATH

Bestämmer platsen för meddelandekataloger för hantering av LC_MESSAGES.

ASYNKRONA HÄNDELSER

Standard.

STANDARD UT

Standard ut ska vara samma som indatafilerna efter bearbetning för makroexpansion.

STANDARD FEL

Standard fel ska användas för att visa strängar med makrot errprint, makrospårning aktiverad med makrot traceon, den definierade texten för makron som skrivs av makrot dumpdef, eller diagnostiska meddelanden.

UTDATAFILER

Inga.

UTVIDGAD BESKRIVNING

Verktyget m4 ska jämföra varje token från indata med uppsättningen inbyggda och användardefinierade makron. Om en token matchar namnet på ett makro ska token ersättas med makrots definierande text, om någon sådan finns, och därefter genomsökas igen efter matchande makronamn. När ingen del av token längre matchar namnet på ett makro ska den skrivas till standard ut. Makron kan ha argument. I sådana fall ska argumenten ersättas in i den definierande texten innan den genomsöks på nytt.

Makroanrop har formen:

namn(arg1, arg2, ..., argn)

Makronamn ska bestå av bokstäver, siffror och understreck, där det första tecknet inte är en siffra. Token som inte har denna form ska inte behandlas som makron.

Programmet som använder m4 ska säkerställa att vänsterparentesen omedelbart följer makronamnet. Om en token som matchar namnet på ett makro inte följs av en vänsterparentes, behandlas den som en användning av makrot utan argument.

Om ett makronamn följs av en vänsterparentes består dess argument av de kommaseparerade token som finns mellan vänsterparentesen och den matchande högerparentesen. Oskyddade blanktecken före varje argument ska ignoreras. Alla andra tecken, inklusive avslutande blanktecken, behålls. Kommatecken som är inneslutna mellan vänster- och högerparentestecken avgränsar inte argument.

Argument definieras och refereras positionsmässigt. Strängen "$1" i den definierande texten ska ersättas med det första argumentet. System ska stödja minst nio argument; endast de första nio kan refereras med strängarna "$1" till "$9", inklusive. Strängen "$0" ersätts med makrots namn. Strängen "$#" ersätts med antalet argument som en sträng. Strängen "$*" ersätts av en lista över alla argument, separerade med kommatecken. Strängen "$@" ersätts av en lista över alla argument separerade med kommatecken, och varje argument citeras med de aktuella vänster- och högerciteringssträngarna. Strängen "${" ger ospecificerat beteende.

Om färre argument anges än vad som finns i makrodefinitionen antas de utelämnade argumenten vara tomma. Det är inte ett fel om fler argument anges än vad som finns i makrodefinitionen.

Inga tecken som är inneslutna mellan matchande vänster- och högerciteringssträngar får någon särskild betydelse, men citeringssträngarna själva tas bort. Som standard består vänsterciteringssträngen av grav accent, backquote, och högerciteringssträngen av akut accent, single quote. Se även makrot changequote.

Kommentarer skrivs ut men genomsöks inte efter matchande makronamn. Som standard består kommentarens startsträng av tecknet nummertecken, och kommentarens slutsträng av en nyrad. Se även makrona changecom och dnl.

Verktyget m4 ska tillhandahålla följande inbyggda makron. De kan omdefinieras, men när detta görs går den ursprungliga betydelsen förlorad. Deras värden ska vara tomma om inte annat anges. I beskrivningarna nedan syftar termen definierande text på makrots värde: bland annat det andra argumentet till makrot define. Förutom det första argumentet till makrot eval ska alla numeriska argument till inbyggda makron tolkas som decimala värden. Strängvärdena som produceras som definierande text av de inbyggda makrona decr, divnum, incr, index, len och sysval ska vara i formen av en decimalkonstant enligt C-språket.

changecom

Makrot changecom ska ange start- och slutsträngarna för kommentarer. Utan argument ska kommentarsmekanismen avaktiveras. Med ett enda icke-tomt argument blir det argumentet startsträng för kommentarer och nyrad blir slutsträng. Med två icke-tomma argument blir det första argumentet startsträng och det andra argumentet slutsträng. Beteendet är ospecificerat om något av argumenten anges men är tomt. System ska stödja kommentarsträngar på minst fem tecken.

changequote

Makrot changequote ska ange start- och slutsträngarna för citering. Utan argument ska citeringssträngarna sättas till standardvärdena, det vill säga grav accent och akut accent. Beteendet är ospecificerat om ett enda argument anges eller om något argument är tomt. Med två icke-tomma argument blir det första argumentet startsträng för citering och det andra argumentet slutsträng. System ska stödja citeringssträngar på minst fem tecken.

decr

Den definierande texten för makrot decr ska vara dess första argument minskat med 1. Det ska vara ett fel att ange ett argument som innehåller icke-numeriska tecken. Beteendet är ospecificerat om decr inte omedelbart följs av en vänsterparentes.

define

Det andra argumentet ska bli den definierande texten för makrot vars namn är det första argumentet. Det är ospecificerat om makrot define tar bort alla tidigare definitioner av makrot som anges av det första argumentet eller bevarar alla utom den aktuella definitionen. Beteendet är ospecificerat om define inte omedelbart följs av en vänsterparentes.

defn

Den definierande texten för makrot defn ska vara den citerade definitionen, med aktuella citeringssträngar, av dess argument. Beteendet är ospecificerat om defn inte omedelbart följs av en vänsterparentes.

divert

Verktyget m4 upprätthåller nio temporära buffertar, numrerade 1 till 9 inklusive. När all indata har bearbetats ska all utdata som har placerats i dessa buffertar skrivas till standard ut i buffertarnas numeriska ordning. Makrot divert ska styra framtida utdata till den buffert som anges av argumentet. Om inget argument anges, eller om argumentet är 0, återupptas normal utdata. Utdata som omdirigeras till en ström med negativt nummer ska kastas bort. Beteendet är implementationsdefinierat om ett strömnummer större än 9 anges. Det ska vara ett fel att ange ett argument som innehåller icke-numeriska tecken.

divnum

Den definierande texten för makrot divnum ska vara numret på den aktuella utdataströmmen som en sträng.

dnl

Makrot dnl ska få m4 att kasta bort alla indatatecken fram till och med nästa nyrad.

dumpdef

Makrot dumpdef ska skriva den definierade texten till standard fel för vart och ett av de makron som anges som argument, eller, om inga argument anges, för alla makron.

errprint

Makrot errprint ska skriva sina argument till standard fel. Beteendet är ospecificerat om errprint inte omedelbart följs av en vänsterparentes.

eval

Makrot eval ska utvärdera sitt första argument som ett aritmetiskt uttryck, med signerad heltalsaritmetik med minst 32-bitars precision. Minst följande C-språksoperatorer ska stödjas, med företräde, associativitet och beteende enligt avsnitt 1.1.2.1, Arithmetic Precision and Operations:

()
unärt +
unärt -
~

!
binärt *
/
%
binärt +
binärt -
<<
>>
<
<=
>
>=
==
!=
binärt &
^
|
&&
||

System ska stödja oktala och hexadecimala tal enligt ISO C-standarden. Det andra argumentet, om det anges, ska ange basen för resultatet. Om argumentet är tomt eller utelämnat är standardvärdet 10. Beteendet är ospecificerat om basen ligger utanför intervallet 2 till 36, inklusive. Det tredje argumentet, om det anges, anger minsta antal siffror i resultatet. Beteendet är ospecificerat om det tredje argumentet är mindre än noll. Det ska vara ett fel att ange ett andra eller tredje argument som innehåller icke-numeriska tecken. Beteendet är ospecificerat om eval inte omedelbart följs av en vänsterparentes.

ifdef

Om det första argumentet till makrot ifdef är definierat ska den definierande texten vara det andra argumentet. Annars ska den definierande texten vara det tredje argumentet, om det anges, eller den tomma strängen om det inte anges. Beteendet är ospecificerat om ifdef inte omedelbart följs av en vänsterparentes.

ifelse

Makrot ifelse tar tre eller fler argument. Om de två första argumenten jämför lika som strängar, efter makroexpansion av båda argumenten, ska den definierande texten vara det tredje argumentet. Om de två första argumenten inte jämför lika och det finns tre argument ska den definierande texten vara tom. Om de två första argumenten inte jämför lika och det finns fyra eller fem argument ska den definierande texten vara det fjärde argumentet. Om de två första argumenten inte jämför lika och det finns sex eller fler argument ska de tre första argumenten kastas bort och bearbetningen starta om med de återstående argumenten. Beteendet är ospecificerat om ifelse inte omedelbart följs av en vänsterparentes.

include

Den definierande texten för makrot include ska vara innehållet i filen som namnges av det första argumentet. Det ska vara ett fel om filen inte kan läsas. Beteendet är ospecificerat om include inte omedelbart följs av en vänsterparentes.

incr

Den definierande texten för makrot incr ska vara dess första argument ökat med 1. Det ska vara ett fel att ange ett argument som innehåller icke-numeriska tecken. Beteendet är ospecificerat om incr inte omedelbart följs av en vänsterparentes.

index

Den definierande texten för makrot index ska vara den första teckenpositionen, som en sträng, i det första argumentet där en sträng som matchar det andra argumentet börjar, med noll som första position, eller -1 om det andra argumentet inte förekommer. Beteendet är ospecificerat om index inte omedelbart följs av en vänsterparentes.

len

Den definierande texten för makrot len ska vara längden, som en sträng, på det första argumentet. Beteendet är ospecificerat om len inte omedelbart följs av en vänsterparentes.

m4exit

Avsluta verktyget m4. Om det första argumentet anges ska det vara slutkoden. Om inget argument anges ska slutkoden vara noll. Det ska vara ett fel att ange ett argument som innehåller icke-numeriska tecken. Om det första argumentet är noll eller inget argument anges, och ett fel tidigare har inträffat, till exempel att en fil-operand inte kunde öppnas, är det ospecificerat om slutstatusen är noll eller icke-noll.

m4wrap

Det första argumentet ska bearbetas när EOF nås. Om makrot m4wrap används flera gånger ska de angivna argumenten bearbetas i den ordning som m4wrap-makrona bearbetades. Beteendet är ospecificerat om m4wrap inte omedelbart följs av en vänsterparentes.

maketemp

Den definierande texten ska vara det första argumentet, med eventuella avslutande X-tecken ersatta med det aktuella process-ID:t som en sträng. Beteendet är ospecificerat om maketemp inte omedelbart följs av en vänsterparentes.

mkstemp

Den definierande texten ska vara som om den vore den resulterande sökvägen efter ett lyckat anrop till funktionen mkstemp() definierad i System Interfaces-volymen av POSIX.1-2017, anropad med det första argumentet till makroanropet. Om en fil skapas ska den filen stängas. Om en fil inte kunde skapas ska verktyget m4 skriva ett diagnostiskt meddelande till standard fel och fortsätta bearbeta indata, men dess slutliga slutstatus ska vara icke-noll. Makrots definierande text ska vara den tomma strängen. Beteendet är ospecificerat om mkstemp inte omedelbart följs av en vänsterparentes.

popdef

Makrot popdef ska ta bort den aktuella definitionen av sina argument och ersätta den med föregående definition. Om det inte finns någon föregående definition blir makrot odefinierat. Beteendet är ospecificerat om popdef inte omedelbart följs av en vänsterparentes.

pushdef

Makrot pushdef ska vara likvärdigt med makrot define, med undantaget att det ska bevara eventuell aktuell definition för senare återhämtning med makrot popdef. Beteendet är ospecificerat om pushdef inte omedelbart följs av en vänsterparentes.

shift

Den definierande texten för makrot shift ska vara en kommaseparerad lista över dess argument utom det första. Varje argument ska citeras med aktuella citeringssträngar. Beteendet är ospecificerat om shift inte omedelbart följs av en vänsterparentes.

sinclude

Makrot sinclude ska vara likvärdigt med makrot include, förutom att det inte ska vara ett fel om filen inte är åtkomlig. Beteendet är ospecificerat om sinclude inte omedelbart följs av en vänsterparentes.

substr

Den definierande texten för makrot substr ska vara delsträngen av det första argumentet som börjar vid den nollbaserade teckenposition som anges av det andra argumentet. Det tredje argumentet, om det anges, ska vara antalet tecken att välja. Om det inte anges ska tecknen från startpunkten till slutet av det första argumentet bli den definierande texten. Det ska inte vara ett fel att ange en startpunkt bortom slutet av det första argumentet, och den definierande texten ska då vara tom. Det ska vara ett fel att ange ett argument som innehåller icke-numeriska tecken. Beteendet är ospecificerat om substr inte omedelbart följs av en vänsterparentes.

syscmd

Makrot syscmd ska tolka sitt första argument som en skalkommandorad. Den definierande texten ska vara strängresultatet från det kommandot. Strängresultatet ska inte genomsökas på nytt efter makron när den definierande texten sätts. Ingen utdatariktning ska utföras av verktyget m4. Slutstatusvärdet från kommandot kan hämtas med makrot sysval. Beteendet är ospecificerat om syscmd inte omedelbart följs av en vänsterparentes.

sysval

Den definierande texten för makrot sysval ska vara slutvärdet för det verktyg som senast anropades av makrot syscmd, som en sträng.

traceon

Makrot traceon ska aktivera spårning för de makron som anges som argument, eller, om inga argument anges, för alla makron. Spårningsutdata ska skrivas till standard fel i ett ospecificerat format.

traceoff

Makrot traceoff ska avaktivera spårning för de makron som anges som argument, eller, om inga argument anges, för alla makron.

translit

Den definierande texten för makrot translit ska vara det första argumentet där varje tecken som förekommer i det andra argumentet ersätts med motsvarande tecken från det tredje argumentet. Om inget ersättningstecken anges för något källtecken därför att det andra argumentet är längre än det tredje argumentet, ska det tecknet tas bort från det första argumentet i translits definierande text. Beteendet är ospecificerat om tecknet - förekommer i det andra eller tredje argumentet någon annanstans än som första eller sista tecken. Beteendet är ospecificerat om samma tecken förekommer mer än en gång i det andra argumentet. Beteendet är ospecificerat om translit inte omedelbart följs av en vänsterparentes.

undefine

Makrot undefine ska ta bort alla definitioner, inklusive sådana som bevarats med makrot pushdef, av de makron som namnges av dess argument. Beteendet är ospecificerat om undefine inte omedelbart följs av en vänsterparentes.

undivert

Makrot undivert ska orsaka omedelbar utmatning av all text i de temporära buffertar som namnges som argument, eller alla temporära buffertar om inga argument anges. Buffertar kan återföras in i andra temporära buffertar. Återföring ska kasta bort innehållet i den temporära bufferten. Beteendet är ospecificerat om ett argument innehåller icke-numeriska tecken.

SLUTSTATUS

Följande slutvärden ska returneras:

0

Lyckad avslutning.

>0

Ett fel inträffade.

Om makrot m4exit används kan slutvärdet anges av indatafilen.

KONSEKVENSER AV FEL

Standard.

Följande avsnitt är informativa.

ANVÄNDNING I PROGRAM

Makrot defn är användbart för att byta namn på makron, särskilt inbyggda makron.

Eftersom eval hänvisar till ISO C-standarden har vissa operationer odefinierat beteende. I vissa implementationer kan division eller restdivision med noll orsaka en fatal signal, även om divisionen sker på den kortslutna grenen av "&&" eller "||". Varje operation som ger spill i signerad aritmetik ger odefinierat beteende. På samma sätt är användning av skiftoperatorer med ett skiftantal som inte är positivt och mindre än precisionen odefinierat, liksom högerskift av ett negativt tal. Historiskt följde inte alla implementationer C-språkets prioritetsregler: ~ och ! hade lägre prioritet än ==; == och != var inte lägre än <; och | var inte lägre än ^. Generös användning av () kan tvinga önskad prioritet även i sådana icke-kompatibla implementationer. Dessutom behandlade vissa traditionella implementationer ^ som en exponentoperator, även om de flesta implementationer numera använder ** som en utökning för detta ändamål.

När ett makro har definierats flera gånger via makrot pushdef är det ospecificerat om makrot define endast ändrar den senaste definitionen, som om med popdef och pushdef, eller ersätter hela definitionsstacken med en enda definition, som om med undefine och pushdef. Ett program som önskar ett särskilt beteende för makrot define i detta fall kan omdefiniera det därefter.

Program bör använda makrot mkstemp i stället för det föråldrade makrot maketemp för att skapa temporära filer.

EXEMPEL

Om filen m4src innehåller raderna:

The value of `VER' is "VER".
ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
ifelse(VER, 1, ``VER'' is `VER'.)
ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
end

ger kommandot

m4 m4src

eller kommandot:

m4 -U VER m4src

följande utdata:

The value of VER is "VER".
VER is not defined.

VER is not 2.
end

Kommandot:

m4 -D VER m4src

ger följande utdata:

The value of VER is "".
VER is defined to be .

VER is not 2.
end

Kommandot:

m4 -D VER=1 m4src

ger följande utdata:

The value of VER is "1".
VER is defined to be 1.
VER is 1.
VER is not 2.
end

Kommandot:

m4 -D VER=2 m4src

ger följande utdata:

The value of VER is "2".
VER is defined to be 2.

VER is 2.
end

BAKGRUND OCH MOTIVERING

Historiskt System V-baserat beteende behandlade "${" i en makrodefinition som två bokstavliga tecken. Denna sekvens lämnas dock ospecificerad så att implementationer kan erbjuda utökningar, till exempel "${11}" för den elfte positionsparametern. Makron kan fortfarande definieras med lämplig användning av nästlad citering för att resultera i en bokstavlig "${" i utdatan efter att den förnyade genomsökningen har tagit bort de nästlade citattecknen.

I den inbyggda funktionen translit behandlade historiskt System V-baserat beteende - som ett bokstavligt tecken. GNU-beteende behandlar det som ett intervall. Denna version av standarden tillåter båda beteendena.

FRAMTIDA RIKTNINGAR

Inga.

SE ÄVEN

c99(1p)

Base Definitions-volymen av POSIX.1-2017, Chapter 8, Environment Variables, Section 12.2, Utility Syntax Guidelines.

COPYRIGHT

Delar av denna text är återgivna och reproducerade i elektronisk form från IEEE Std 1003.1-2017, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. Vid eventuella skillnader mellan denna version och den ursprungliga IEEE- och The Open Group-standarden är den ursprungliga standarden det avgörande dokumentet. Den ursprungliga standarden kan erhållas online på http://www.opengroup.org/unix/online.html.

Eventuella typografiska fel eller formateringsfel som förekommer på denna sida har sannolikt införts vid konverteringen av källfilerna till manualsidesformat. För att rapportera sådana fel, se https://www.kernel.org/doc/man-pages/reporting_bugs.html.

IEEE/The Open Group                2017                            M4(1P)